@cueframe/kernel 0.0.1

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

@@ -0,0 +1,140 @@
+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;
+        src_h: number;
+    };
+    outW: number;
+    outH: number;
+    cx: number;
+    cy: number;
+    zoomScale: number;
+    verticalBias: number;
+    lateralBias: number;
+    reframe?: ReframeAdjustment;
+}): {
+    tx: number;
+    ty: number;
+    tyNoShift: number;
+    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;
+    sections: CropSection[];
+    trimStartFrames: number;
+    durationInFrames: number;
+    outW: number;
+    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[];
+    trimStartFrames: number;
+    durationInFrames: number;
+    outW: number;
+    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/cropProjection.js

@@ -0,0 +1,257 @@
+/**
+ * Crop→output projection — the SINGLE SOURCE OF TRUTH for mapping source-space
+ * trajectory/face geometry into OUTPUT (post-crop) coordinates. Previously these
+ * primitives lived in the Remotion app layer (packages/execution/render-entry/src/
+ * CropFromTrajectory.tsx + floor/sourceToOutput.ts); lifted here so BOTH the
+ * render path (buildFloorInput, CropFromTrajectory) AND the Director activity
+ * (structure-first graphics keep-outs) derive output geometry from ONE copy —
+ * no duplication, no approximation.
+ *
+ * All functions are pure math (no React/Remotion). The section-aware
+ * output→trajectory map + fail-loud coverage checks are preserved verbatim.
+ */
+import { CueframeError, encodeError } from "@cueframe/errors";
+import { activeFaceKeepOutSeries, boundingBox } from "./composition-floor";
+// Max fps-conversion rounding error at a segment seam: round(sec*srcFps) on the
+// segment edge vs round(...*srcFps/fps) in the frame map can disagree by ~1
+// frame; 2 is that bound plus one frame of safety. NOT a tunable behavior knob.
+export 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 function resolveSegmentAt(traj, srcFrame) {
+    for (const seg of traj.segments) {
+        const segStartFrame = Math.round(seg.start_sec * traj.src_fps);
+        const segEndFrame = Math.round(seg.end_sec * traj.src_fps);
+        if (srcFrame >= segStartFrame && srcFrame < segEndFrame) {
+            const inSegIdx = Math.max(0, Math.min(srcFrame - segStartFrame, seg.centers.length - 1));
+            return { seg, inSegIdx };
+        }
+    }
+    if (traj.segments.length === 0) {
+        throw new Error(encodeError(new CueframeError('trajectory_unresolved', 'trajectory has no segments')));
+    }
+    // Out of every segment: find the nearest edge + its distance.
+    let best = traj.segments[0];
+    let bestInIdx = 0;
+    let bestDist = Infinity;
+    for (const seg of traj.segments) {
+        const a = Math.round(seg.start_sec * traj.src_fps);
+        const b = Math.round(seg.end_sec * traj.src_fps);
+        const before = srcFrame < a;
+        const dist = before ? a - srcFrame : srcFrame - (b - 1);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = seg;
+            bestInIdx = before ? 0 : Math.max(0, seg.centers.length - 1);
+        }
+    }
+    if (bestDist > FRAME_ROUNDING_TOLERANCE) {
+        throw new Error(encodeError(new CueframeError('trajectory_coverage_gap', `srcFrame ${srcFrame} is ${bestDist} frames outside every trajectory segment ` +
+            `(nearest [${best.start_sec.toFixed(2)}–${best.end_sec.toFixed(2)}s]). A coverage/` +
+            `mapping bug (a cropIntent gap with no excludedRange, or an output→trajectory frame ` +
+            `mismatch) — refusing to silently clamp a crop onto the wrong frames.`, { srcFrame, gapFrames: bestDist, nearest: [best.start_sec, best.end_sec] })));
+    }
+    // Within rounding slack of an edge → clamp (legitimate seam rounding).
+    return { seg: best, inSegIdx: Math.max(0, Math.min(bestInIdx, best.centers.length - 1)) };
+}
+/**
+ * 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 function outputToTrajectoryFrame(sections, trimStartFrames, outFrame, srcFps, fps) {
+    let cum = 0;
+    for (const s of sections) {
+        if (outFrame < cum + s.durationInFrames) {
+            const clipFramesAtFps = s.sourceInFrames - trimStartFrames + (outFrame - cum);
+            return Math.round((clipFramesAtFps * srcFps) / fps);
+        }
+        cum += s.durationInFrames;
+    }
+    // Tail rounding overrun (±1-frame seam at the very end) — the sections tile the
+    // whole output by construction; clamp to the last span's final played frame.
+    const last = sections[sections.length - 1];
+    const clipFramesAtFps = last.sourceInFrames - trimStartFrames + (last.durationInFrames - 1);
+    return Math.round((clipFramesAtFps * srcFps) / fps);
+}
+/**
+ * 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 function computeCropTransform(input) {
+    const { traj, outW, outH, cx, cy, zoomScale, verticalBias, lateralBias, reframe = { kind: 'transform', dy: 0, zoom: 1 }, } = input;
+    const reframeDy = reframe.kind === 'transform' ? reframe.dy : 0;
+    const faceScale = reframe.kind === 'transform' ? reframe.zoom : 1;
+    // Crop window dimensions in source coords (largest output-aspect rect that fits
+    // the source, scaled by zoom). zoom_scale<1.0 shrinks (= more zoom).
+    const outAR = outW / outH;
+    const srcAR = traj.src_w / traj.src_h;
+    let cropW;
+    let cropH;
+    if (srcAR > outAR) {
+        cropH = traj.src_h;
+        cropW = traj.src_h * outAR;
+    }
+    else {
+        cropW = traj.src_w;
+        cropH = traj.src_w / outAR;
+    }
+    const bakedZoom = Math.max(0.4, Math.min(1.0, zoomScale));
+    const effectiveZoom = Math.min(1.0, bakedZoom / Math.max(faceScale, 0.01));
+    cropW *= effectiveZoom;
+    cropH *= effectiveZoom;
+    // Scale source uniformly so crop window = output dimensions.
+    const scale = outW / cropW;
+    const scaledSrcW = traj.src_w * scale;
+    const scaledSrcH = traj.src_h * scale;
+    // Translate so the crop center sits at the output center, with bias applied in
+    // crop-window units (matches the bake's center+bias math).
+    const biasXPx = cropW * lateralBias * scale;
+    const biasYPx = cropH * verticalBias * scale;
+    const txRaw = outW / 2 - cx * scaledSrcW + biasXPx;
+    const tyNoShift = outH / 2 - cy * scaledSrcH + biasYPx;
+    // Reframe-yield: slide the source by dy·outH (dy<0 raises the subject).
+    const tyRaw = tyNoShift + reframeDy * outH;
+    // Coverage clamp — the scaled source must ALWAYS cover the output canvas (no
+    // black edge). A GEOMETRIC INVARIANT (cx/cy are raw face centroids).
+    const tx = Math.min(0, Math.max(outW - scaledSrcW, txRaw));
+    const ty = Math.min(0, Math.max(outH - scaledSrcH, tyRaw));
+    return { tx, ty, tyNoShift, scaledSrcW, scaledSrcH };
+}
+/**
+ * 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 function sourceRectToOutput(src, t, outW, outH) {
+    return {
+        x: (t.tx + src.x * t.scaledSrcW) / outW,
+        y: (t.ty + src.y * t.scaledSrcH) / outH,
+        w: (src.w * t.scaledSrcW) / outW,
+        h: (src.h * t.scaledSrcH) / outH,
+    };
+}
+/**
+ * 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 function buildSubjectsOutput(args) {
+    const { traj, sections, trimStartFrames, durationInFrames, outW, outH, fps } = args;
+    const series = new Map();
+    const activeBySubject = new Map();
+    const order = [];
+    const emptySeries = () => Array(durationInFrames).fill(null);
+    for (let f = 0; f < durationInFrames; f++) {
+        const srcFrame = outputToTrajectoryFrame(sections, trimStartFrames, f, traj.src_fps, fps);
+        const { seg, inSegIdx } = resolveSegmentAt(traj, srcFrame);
+        const [cx, cy] = seg.centers[inSegIdx];
+        const transform = computeCropTransform({
+            traj: { src_w: traj.src_w, src_h: traj.src_h },
+            outW,
+            outH,
+            cx,
+            cy,
+            zoomScale: seg.zoom_scale,
+            verticalBias: seg.vertical_bias,
+            lateralBias: seg.lateral_bias,
+        });
+        for (const subj of seg.subjects) {
+            if (!series.has(subj.face_id)) {
+                series.set(subj.face_id, emptySeries());
+                activeBySubject.set(subj.face_id, subj.active_windows ?? []);
+                order.push(subj.face_id);
+            }
+            const srcBox = subj.face_box_series[inSegIdx];
+            if (!srcBox)
+                continue;
+            const [x, y, w, h] = srcBox;
+            series.get(subj.face_id)[f] = sourceRectToOutput({ x, y, w, h }, transform, outW, outH);
+        }
+    }
+    return order.map((id) => ({
+        id,
+        faceBoxSeries: series.get(id),
+        activeWindows: (activeBySubject.get(id) ?? []).map(([startFrame, endFrame]) => ({ startFrame, endFrame })),
+    }));
+}
+/**
+ * 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 function faceKeepOutForWindow(subjects, startFrame, endFrame, depthMode = false) {
+    const series = activeFaceKeepOutSeries(subjects, depthMode);
+    const inWindow = series
+        .slice(Math.max(0, startFrame), Math.max(0, endFrame))
+        .filter((r) => r != null);
+    return inWindow.length ? [boundingBox(inWindow)] : [];
+}
+/**
+ * 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 function buildSilhouetteKeepOutOutput(args) {
+    const { traj, silhouette, sections, trimStartFrames, durationInFrames, outW, outH, fps } = args;
+    const series = new Array(durationInFrames).fill(null);
+    for (let f = 0; f < durationInFrames; f++) {
+        const srcFrame = outputToTrajectoryFrame(sections, trimStartFrames, f, traj.src_fps, fps);
+        const srcBox = silhouette.bboxAtSourceFrame(srcFrame);
+        if (!srcBox)
+            continue;
+        const { seg, inSegIdx } = resolveSegmentAt(traj, srcFrame);
+        const [cx, cy] = seg.centers[inSegIdx];
+        const transform = computeCropTransform({
+            traj: { src_w: traj.src_w, src_h: traj.src_h },
+            outW,
+            outH,
+            cx,
+            cy,
+            zoomScale: seg.zoom_scale,
+            verticalBias: seg.vertical_bias,
+            lateralBias: seg.lateral_bias,
+        });
+        const out = sourceRectToOutput(srcBox, transform, outW, outH);
+        const x = Math.max(0, Math.min(1, out.x));
+        const y = Math.max(0, Math.min(1, out.y));
+        const right = Math.max(0, Math.min(1, out.x + out.w));
+        const bot = Math.max(0, Math.min(1, out.y + out.h));
+        series[f] = { x, y, w: Math.max(0, right - x), h: Math.max(0, bot - y) };
+    }
+    return series;
+}
+/**
+ * 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 function silhouetteKeepOutForWindow(series, startFrame, endFrame) {
+    const inWindow = series
+        .slice(Math.max(0, startFrame), Math.max(0, endFrame))
+        .filter((r) => r != null && r.w > 0 && r.h > 0);
+    return inWindow.length ? [boundingBox(inWindow)] : [];
+}

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

@@ -0,0 +1,7 @@
+export * from "./brandKit.js";
+export * from "./cardTokens.js";
+export * from "./composition-floor.js";
+export * from "./safe-zones.js";
+export * from "./behind-placement.js";
+export * from "./occlusion-budget.js";
+export * from "./cropProjection.js";

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

@@ -0,0 +1,7 @@
+export * from "./brandKit";
+export * from "./cardTokens";
+export * from "./composition-floor";
+export * from "./safe-zones";
+export * from "./behind-placement";
+export * from "./occlusion-budget";
+export * from "./cropProjection";

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

@@ -0,0 +1,67 @@
+/**
+ * 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;
+    w: number;
+    h: number;
+}, frame: MatteGeometryFrame): {
+    total: number;
+    topHalf: number;
+};

package/dist/_members/composition/projection/occlusion-budget.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+/** 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 const BUDGET = { minBite: 0.15, maxCoverage: 0.65, maxTopHalf: 0.35 };
+/** Behind hero text extent heuristic (calibration constants; Phase-7 fixtures tune). */
+export const BEHIND_TEXT_EXTENT = { heightFrac: 0.18 };
+/**
+ * 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 function evaluateOcclusionBudget(samples, opts = { textBearing: true }) {
+    let maxTotal = 0;
+    for (const s of samples) {
+        if (opts.textBearing && s.topHalf > BUDGET.maxTopHalf) {
+            return { verdict: "tops-occluded", worstFrame: s.f };
+        }
+        if (s.total > BUDGET.maxCoverage) {
+            return { verdict: "swallow", worstFrame: s.f };
+        }
+        if (s.total > maxTotal)
+            maxTotal = s.total;
+    }
+    if (maxTotal < BUDGET.minBite)
+        return { verdict: "no-depth" };
+    return { verdict: "pass" };
+}
+/**
+ * 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 function estimateCoverage(textRect, frame) {
+    if (!frame.bbox)
+        return { total: 0, topHalf: 0 };
+    const subject = {
+        x: frame.bbox[0],
+        y: frame.bbox[1],
+        w: frame.bbox[2] - frame.bbox[0],
+        h: frame.bbox[3] - frame.bbox[1],
+    };
+    const total = coverageOfRect(textRect, subject, frame.cols);
+    const topRect = { x: textRect.x, y: textRect.y, w: textRect.w, h: textRect.h / 2 };
+    const topHalf = coverageOfRect(topRect, subject, frame.cols, frame.rows);
+    return { total: clamp01(total), topHalf: clamp01(topHalf) };
+}
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+function intersect(a, b) {
+    const x0 = Math.max(a.x, b.x);
+    const y0 = Math.max(a.y, b.y);
+    const x1 = Math.min(a.x + a.w, b.x + b.w);
+    const y1 = Math.min(a.y + a.h, b.y + b.h);
+    if (x1 <= x0 || y1 <= y0)
+        return null;
+    return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+/** Unweighted mean of the marginal buckets a [lo, hi) frame-normalized span
+ *  overlaps. Bucket i covers [i/N, (i+1)/N). */
+function meanBuckets(buckets, lo, hi) {
+    const n = buckets.length;
+    if (n === 0 || hi <= lo)
+        return 0;
+    const i0 = Math.max(0, Math.min(n - 1, Math.floor(lo * n)));
+    const i1 = Math.max(0, Math.min(n - 1, Math.ceil(hi * n) - 1));
+    let sum = 0;
+    for (let i = i0; i <= i1; i++)
+        sum += buckets[i];
+    return sum / (i1 - i0 + 1);
+}
+/** (overlap area / rect area) × mean col coverage over the overlap's x-span,
+ *  optionally × mean row coverage over its y-span (the topHalf refinement). */
+function coverageOfRect(rect, subject, cols, rows) {
+    const rectArea = rect.w * rect.h;
+    if (rectArea <= 0)
+        return 0;
+    const inter = intersect(rect, subject);
+    if (!inter)
+        return 0;
+    const areaFrac = (inter.w * inter.h) / rectArea;
+    const meanCol = meanBuckets(cols, inter.x, inter.x + inter.w);
+    const rowWeight = rows ? meanBuckets(rows, inter.y, inter.y + inter.h) : 1;
+    return areaFrac * meanCol * rowWeight;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * 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;