@cueframe/kernel 0.1.0 → 0.1.1

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

@@ -1,257 +0,0 @@
-/**
- * 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.js

@@ -1,7 +0,0 @@
-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.js

@@ -1,104 +0,0 @@
-/**
- * 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.js

@@ -1,99 +0,0 @@
-/** 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. */
-// v2: platform-name normalization (ig→reels, youtube→shorts) so the suggestion
-// vocabulary resolves to a profile instead of silently falling to broadcast.
-export const SAFE_ZONE_PROFILE_VERSION = "safezones-v2-2026.06.05";
-/** A centered inset of the output rect by `(1 - frac)/2` on every edge. For
- *  fractions-of-output coordinates this IS the title/action-safe margin and is
- *  aspect-agnostic (the output rect already carries the aspect). */
-function inset(frac) {
-    const m = (1 - frac) / 2;
-    return { x: m, y: m, w: frac, h: frac };
-}
-const TITLE_SAFE_FRAC = 0.9;
-const ACTION_SAFE_FRAC = 0.93;
-function broadcast() {
-    return { exclusions: [], titleSafe: inset(TITLE_SAFE_FRAC), actionSafe: inset(ACTION_SAFE_FRAC) };
-}
-/**
- * Platform-UI exclusion rects per (platform, aspect). Fractions of output.
- * Extend as a platform changes its chrome. Keyed off the suggestion's
- * `platforms[]` + `format` (the destination the agent already chose).
- */
-const PROFILES = {
-    tiktok: {
-        "9:16": [
-            { x: 0, y: 0.82, w: 1, h: 0.18 }, // bottom username/caption strip
-            { x: 0.86, y: 0.45, w: 0.14, h: 0.4 }, // right action rail (like/comment/share)
-            { x: 0, y: 0, w: 1, h: 0.06 }, // top (following/for-you tabs)
-        ],
-    },
-    reels: {
-        "9:16": [
-            { x: 0, y: 0.8, w: 1, h: 0.2 }, // bottom caption + audio strip
-            { x: 0.85, y: 0.42, w: 0.15, h: 0.42 }, // right action rail
-        ],
-    },
-    shorts: {
-        "9:16": [
-            { x: 0, y: 0.84, w: 1, h: 0.16 }, // bottom title/channel strip
-            { x: 0.88, y: 0.4, w: 0.12, h: 0.4 }, // right action rail
-        ],
-    },
-};
-/**
- * Map the suggestion's platform vocabulary (what the agent/clip pass emits) to a
- * PROFILES key. Suggestions say `ig`/`instagram`/`youtube`; the profile table is
- * keyed by the surface-with-chrome (`reels`/`shorts`/`tiktok`). Without this, an
- * `ig` clip silently falls through to broadcast and captions sit under the Reels
- * UI. Unknown names pass through unchanged (→ broadcast fallback).
- */
-const PLATFORM_ALIASES = {
-    ig: "reels",
-    instagram: "reels",
-    reels: "reels",
-    igreels: "reels",
-    yt: "shorts",
-    youtube: "shorts",
-    ytshorts: "shorts",
-    shorts: "shorts",
-    tiktok: "tiktok",
-    tt: "tiktok",
-};
-/** Normalize a platform name to a PROFILES key (lowercased, aliased). */
-export function normalizePlatform(platform) {
-    const k = (platform ?? "").trim().toLowerCase();
-    return PLATFORM_ALIASES[k] ?? k;
-}
-/**
- * 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 function lookupSafeZones(platform, aspect) {
-    const base = broadcast();
-    const key = normalizePlatform(platform);
-    // Exact platform when known; otherwise the UNION of every platform's chrome
-    // for this aspect — so when the destination isn't threaded, captions/overlays
-    // still clear ANY vertical surface's UI (the robust default) rather than
-    // silently dropping to broadcast and sitting under the bottom strip. A
-    // non-social aspect (16:9) has no profiles → union is empty → broadcast.
-    const exclusions = PROFILES[key]?.[aspect] ?? unionExclusionsForAspect(aspect);
-    // Copy the rects so callers can't mutate the shared table.
-    return { ...base, exclusions: exclusions.map((r) => ({ ...r })) };
-}
-/** Every known platform's exclusion rects for an aspect, concatenated. The
- *  caller (placeInLegalArea) avoids all of them, so overlap is fine — the net
- *  effect is the most-constraining chrome across platforms. */
-function unionExclusionsForAspect(aspect) {
-    const all = [];
-    for (const platform of Object.keys(PROFILES)) {
-        const ex = PROFILES[platform]?.[aspect];
-        if (ex)
-            all.push(...ex);
-    }
-    return all;
-}

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

@@ -1,115 +0,0 @@
-/**
- * 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 function coverVisibleFraction(source, target) {
-    const s = source.width / source.height;
-    const t = target.width / target.height;
-    if (!Number.isFinite(s) || !Number.isFinite(t) || s <= 0 || t <= 0)
-        return 1;
-    return Math.min(s, t) / Math.max(s, t);
-}
-/**
- * Warn below this much of the source surviving. 0.75 = "more than a quarter of
- * the picture is being thrown away" — comfortably past a 4:3-in-16:9 letterbox
- * nudge (0.84) and well inside portrait-in-landscape (0.38).
- */
-const VISIBLE_FRACTION_FLOOR = 0.75;
-/** How many clips to name before eliding. */
-const MAX_NAMED = 6;
-/** Collect every `kind:'media'` clip source, with its enclosing clip's id. */
-function collectMediaClips(value, nearestId, out) {
-    if (Array.isArray(value)) {
-        for (const v of value)
-            collectMediaClips(v, nearestId, out);
-        return;
-    }
-    if (value === null || typeof value !== "object")
-        return;
-    const obj = value;
-    const id = typeof obj.id === "string" ? obj.id : nearestId;
-    if (obj.kind === "media" && typeof obj.mediaId === "string") {
-        const reframe = obj.reframe;
-        const hasReframe = Array.isArray(reframe?.segments) && reframe.segments.length > 0;
-        out.push({
-            mediaId: obj.mediaId,
-            hasCamera: hasReframe || obj.kenBurns != null,
-            ...(id !== undefined ? { clipId: id } : {}),
-        });
-        return;
-    }
-    for (const v of Object.values(obj))
-        collectMediaClips(v, id, out);
-}
-/**
- * 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 function detectAspectCropLoss(composition, dimensionsByMediaId, target) {
-    const placed = [];
-    collectMediaClips(composition, undefined, placed);
-    if (placed.length === 0)
-        return [];
-    const offenders = [];
-    const seen = new Set();
-    for (const clip of placed) {
-        if (clip.hasCamera)
-            continue;
-        const dim = dimensionsByMediaId[clip.mediaId];
-        if (!dim?.width || !dim?.height)
-            continue; // dimensions arrive lazily — never guess
-        const visible = coverVisibleFraction({ width: dim.width, height: dim.height }, target);
-        if (visible >= VISIBLE_FRACTION_FLOOR)
-            continue;
-        const label = clip.clipId ?? clip.mediaId;
-        if (seen.has(label))
-            continue;
-        seen.add(label);
-        offenders.push({ label, lostPct: Math.round((1 - visible) * 100) });
-    }
-    if (offenders.length === 0)
-        return [];
-    const worst = offenders.reduce((a, b) => (b.lostPct > a.lostPct ? b : a));
-    const shown = offenders
-        .slice(0, MAX_NAMED)
-        .map((o) => `${o.label} (−${o.lostPct}%)`)
-        .join(", ");
-    const elided = offenders.length > MAX_NAMED ? ` (+${offenders.length - MAX_NAMED} more)` : "";
-    return [
-        `aspect_crop_loss — ${offenders.length} clip${offenders.length === 1 ? "" : "s"} ` +
-            `${offenders.length === 1 ? "is" : "are"} shaped very differently from the ` +
-            `${target.width}×${target.height} output and author no camera, so each is centre-cropped ` +
-            `to fill — discarding up to ${worst.lostPct}% of the picture with faces and subjects as ` +
-            `likely to fall outside the crop as inside it: ${shown}${elided}. Author a \`reframe\` ` +
-            `(focus a face, a point, or all-faces) or a \`kenBurns\` move on these clips, or render a ` +
-            `format closer to their shape. Note \`fit:"contain"\` does NOT avoid this for stills — ` +
-            `images are cropped by the still trajectory, which centres when it has no focus.`,
-    ];
-}

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

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