@cueframe/kernel 0.1.0 → 0.1.1

package/dist/_members/composition/projection/composition-floor.js

@@ -1,582 +0,0 @@
-/**
- * Composition FLOOR — the deterministic correctness layer of the
- * aspect-agnostic composition design system. The spatial sibling of brand `clampToFloor`:
- * `clampToFloor` guarantees a COLOR clears a contrast floor; `resolveComposition-
- * Floor` guarantees a LAYOUT clears the spatial/legibility floors.
- *
- * Pure, deterministic, ZERO I/O, ZERO proprietary imports (it is on the OSS
- * render path — spec §16). Home: `@cueframe/composition/projection`. APCA
- * math is consumed from `@cueframe/brand-derivation` (the package that owns it) —
- * never re-implemented here, never a proxy.
- *
- * Coordinate system: every Rect is FRACTIONS of the output rect, origin
- * TOP-LEFT, y-down, all in [0,1]. One math path for 9:16/1:1/4:5/16:9 because
- * the output rect already carries the aspect.
- *
- * The FLOOR invariants it guarantees (spec §2):
- *   1. Face never occluded — the face keep-out has zero overlap with caption
- *      text / `inset` opaque graphics.
- *   2. Captions/graphic text legible — APCA worst-tile Lc ≥ CAPTION_LC_FLOOR
- *      over the real backdrop beneath the element.
- *   3. A usable, composed area exists for every REQUIRED element — the reframe
- *      yields space (reposition → zoom → designed mat, never a flat letterbox on
- *      vertical); only NON-required elements may drop.
- *   4. Destination safe zones respected (platform UI + title/action-safe).
- *
- * The algorithm is LINEAR (yield-before-place, one stage per clip) — no feedback
- * loop, fully deterministic. Legibility is a pure DECISION over a caller-supplied
- * luminance summary; the actual pixel sampling lives in the render consumer.
- *
- * The contract is MULTI-SUBJECT NATIVE (`subjects[]`, `LayoutIntent`) so the
- * speaker-switch / split layout work (spec §8) extends it without a contract
- * rewrite. THIS module fully implements single-focus placement and a correct
- * N-subject union keep-out (captions never occlude ANY face); the DESIGNED
- * split/stacked/speaker-switch geometry is a later plan and is reported via
- * `LayoutIntent` + a diagnostic, never silently single-focused.
- */
-import { apcaLcFromLuminance, relativeLuminance } from "@cueframe/brand-derivation";
-import { lookupSafeZones } from "./safe-zones";
-// Re-export the hex-input APCA primitive so composition CONSUMERS that may import
-// composition but NOT brand-derivation directly (notably the @cueframe/evaluation
-// contrast critic — evaluation's package.json declares only composition+perception)
-// reach the SAME APCA math. Single source of truth: the math stays owned by
-// @cueframe/brand-derivation — never re-implemented here, never a proxy (see the
-// module header). `apcaLcFromLuminance` (luminance-input sibling) is already used
-// internally by decideLegibility below.
-export { apcaLc } from "@cueframe/brand-derivation";
-/** 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. */
-// v2: speaker-switch tracks the active speaker's keep-out (not the union) so
-// captions clear the in-frame speaker on 2-shots (spec §8, item G).
-// v3: co-view (captions-behind) reframe widens the crop so the silhouette clears
-// the centred caption laterally (coViewReframe) — fixes captions vanishing behind
-// the body; the reframe zoom-yield is now applied (no longer deferred).
-// v4: co-view silhouette target tightened 0.58→0.45 for a more readable body-bite.
-// floor-v5: §22.2 captions-behind eligibility gate is LIVE — buildFloorInput
-// injects the captionsBehind summary on depthMode clips, so a low-presence
-// (b-roll / no-speaker) depthMode clip now DEGRADES to a lower-third caption
-// (output differs from v4). The bake-time matte-coverage scalar is a follow-on
-// refinement; until then the coverage gate is skipped (presence + sizing gate).
-export const FLOOR_VERSION = "floor-v6-2026.06.09";
-// ── Constants (all versioned via FLOOR_VERSION) ──────────────────────────────
-/** 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 const FACE_PADDING = { top: 0.6, bottom: 0.3, 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 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 const MIN_ZOOM = 0.4;
-const clamp01 = (v) => Math.max(0, Math.min(1, v));
-// ── Face keep-out ────────────────────────────────────────────────────────────
-/** 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 function faceKeepOut(face, depthMode = false) {
-    if (!face)
-        return null;
-    const padX = FACE_PADDING.side * face.w;
-    const top = FACE_PADDING.top * face.h;
-    // depthMode relaxes the LOWER edge only (spec §12): the torso band is legible-
-    // behind via z-order, so no bottom growth — keeps top/sides hard.
-    const bottom = depthMode ? 0 : FACE_PADDING.bottom * face.h;
-    const x = clamp01(face.x - padX);
-    const y = clamp01(face.y - top);
-    const right = clamp01(face.x + face.w + padX);
-    const bot = clamp01(face.y + face.h + bottom);
-    return { x, y, w: right - x, h: bot - y };
-}
-/** Axis-aligned bounding box of a set of rects. */
-export function boundingBox(rects) {
-    const x = Math.min(...rects.map((r) => r.x));
-    const y = Math.min(...rects.map((r) => r.y));
-    const right = Math.max(...rects.map((r) => r.x + r.w));
-    const bot = Math.max(...rects.map((r) => r.y + r.h));
-    return { x, y, w: right - x, h: bot - y };
-}
-/** 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 function unionFaceKeepOutSeries(subjects, depthMode = false) {
-    const frameCount = subjects.reduce((m, s) => Math.max(m, s.faceBoxSeries.length), 0);
-    const series = [];
-    for (let f = 0; f < frameCount; f++) {
-        const present = [];
-        for (const s of subjects) {
-            const k = faceKeepOut(s.faceBoxSeries[f] ?? null, depthMode);
-            if (k)
-                present.push(k);
-        }
-        series.push(present.length ? boundingBox(present) : null);
-    }
-    return series;
-}
-/** 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 function activeFaceKeepOutSeries(subjects, depthMode = false) {
-    const frameCount = subjects.reduce((m, s) => Math.max(m, s.faceBoxSeries.length), 0);
-    const series = [];
-    for (let f = 0; f < frameCount; f++) {
-        let active = subjects.find((s) => (s.activeWindows ?? []).some((w) => f >= w.startFrame && f < w.endFrame));
-        if (!active || active.faceBoxSeries[f] == null) {
-            active = subjects.find((s) => s.faceBoxSeries[f] != null);
-        }
-        series.push(active ? faceKeepOut(active.faceBoxSeries[f] ?? null, depthMode) : null);
-    }
-    return series;
-}
-// ── Layout intent ────────────────────────────────────────────────────────────
-/** 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 function resolveLayoutIntent(subjects) {
-    if (subjects.length <= 1)
-        return "single-focus";
-    const anyActiveWindows = subjects.some((s) => (s.activeWindows?.length ?? 0) > 0);
-    return anyActiveWindows ? "speaker-switch" : "split";
-}
-// ── Reframe-yield (yield BEFORE place; spec §6.4) ────────────────────────────
-/**
- * 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 function reframeYield(input) {
-    const { maxFaceKeepOut: f, neededBand } = input;
-    if (neededBand <= 0)
-        return { kind: "transform", dy: 0, zoom: 1 };
-    const bandBelow = 1 - (f.y + f.h);
-    if (bandBelow >= neededBand)
-        return { kind: "transform", dy: 0, zoom: 1 };
-    // 1) reposition: slide the source up so the keep-out's bottom leaves the band.
-    const dyNeeded = neededBand - bandBelow;
-    const headroomAbove = f.y; // room to raise the face before it clips the top
-    if (dyNeeded <= headroomAbove)
-        return { kind: "transform", dy: -dyNeeded, zoom: 1 };
-    // 2) zoom-out: after using all headroom, shrink the subject to free the rest,
-    //    capped at the source-fit floor.
-    const zoom = (f.h - (dyNeeded - headroomAbove)) / f.h;
-    if (zoom > MIN_ZOOM)
-        return { kind: "transform", dy: -headroomAbove, zoom };
-    // 3) designed mat — a reserved BAND at the bottom (never a flat letterbox).
-    return { kind: "mat", rect: { x: 0, y: 1 - neededBand, w: 1, h: neededBand } };
-}
-/**
- * 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 function reframeYieldTop(input) {
-    const { maxFaceKeepOut: f, neededBand } = input;
-    if (neededBand <= 0)
-        return { kind: "transform", dy: 0, zoom: 1 };
-    const bandAbove = f.y;
-    if (bandAbove >= neededBand)
-        return { kind: "transform", dy: 0, zoom: 1 };
-    // 1) reposition: slide the source DOWN (dy>0) so the keep-out's TOP leaves the
-    //    band — bounded by the room below the face before it clips the bottom edge.
-    const dyNeeded = neededBand - bandAbove;
-    const roomBelow = 1 - (f.y + f.h);
-    if (dyNeeded <= roomBelow)
-        return { kind: "transform", dy: dyNeeded, zoom: 1 };
-    // 2) zoom-out: after using the room below, shrink the subject to free the rest.
-    const zoom = (f.h - (dyNeeded - roomBelow)) / f.h;
-    if (zoom > MIN_ZOOM)
-        return { kind: "transform", dy: roomBelow, zoom };
-    // 3) no fake band — even max zoom can't fit it → ineligible (degrade to front).
-    return 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 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 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 function coViewReframe(maxFaceKeepOut) {
-    const silhouetteW = SILHOUETTE_TO_KEEPOUT_W * maxFaceKeepOut.w;
-    if (silhouetteW <= COVIEW_MAX_SILHOUETTE_W)
-        return { kind: "transform", dy: 0, zoom: 1 };
-    const zoom = Math.max(MIN_ZOOM, COVIEW_MAX_SILHOUETTE_W / silhouetteW);
-    return { kind: "transform", dy: 0, zoom };
-}
-// ── Captions-behind-speaker eligibility (spec §22.2 — the moat gate) ──────────
-// Decides WHETHER the depth effect applies; sizing is coViewReframe above.
-// NOT single-speaker-only: eligible whenever an ACTIVE speaker's silhouette
-// occludes the caption band in the readable range — the floor's
-// activeFaceKeepOutSeries then follows the active speaker per-window (single OR
-// two-shot OR speaker-switch). When ineligible (or a window has no silhouette)
-// the caller DEGRADES to a flat, floor-placed caption — never drops it.
-// Thresholds are CALIBRATION DEFAULTS, tuned against the golden set (R1–R10),
-// not theory.
-export const MIN_ACTIVE_SPEAKER_PRESENCE = 0.6; // ≥ this fraction of clip frames have an active speaker (else ~b-roll/no-face)
-export const COVIEW_MIN_BAND_COVERAGE = 0.15; // < this: too little body-bite to read as depth → flat caption
-export const COVIEW_MAX_BAND_COVERAGE = 0.7; // > this: silhouette eats the words (the 100%-occluded bug) → flat caption
-/**
- * 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 function captionsBehindEligible(input) {
-    // Presence gates the "is there a speaker to put captions behind" case (single
-    // OR two-shot). Low presence ⇒ b-roll / no-speaker ⇒ degrade.
-    if (input.activeSpeakerPresenceFraction < MIN_ACTIVE_SPEAKER_PRESENCE) {
-        return { eligible: false, reason: "no-active-speaker" };
-    }
-    // Coverage gate applies ONLY when the bake-time scalar is measured. `null` =
-    // not yet computed ⇒ skip it and rely on presence + the coViewReframe sizing
-    // (which already caps gross over-occlusion at COVIEW_MAX_SILHOUETTE_W). A
-    // measured value of ~0 (silhouette doesn't reach the band) falls into
-    // coverage-too-low; the no-person case is already handled by presence above.
-    if (input.activeBandCoverage != null) {
-        if (input.activeBandCoverage < COVIEW_MIN_BAND_COVERAGE) {
-            return { eligible: false, reason: "coverage-too-low" };
-        }
-        if (input.activeBandCoverage > COVIEW_MAX_BAND_COVERAGE) {
-            return { eligible: false, reason: "coverage-too-high" };
-        }
-    }
-    if (!input.legible) {
-        return { eligible: false, reason: "illegible" };
-    }
-    return { eligible: true, reason: "eligible" };
-}
-const CENTER = 0.5;
-const MIN_CAPTION_WIDTH = 0.5; // never squeeze a caption narrower than this to clear a side rail
-/** A blocker is a vertical-BAND blocker if it straddles the horizontal centre
- *  (face keep-out, top/bottom UI strips, a centred caption already placed) — it
- *  blocks the band's vertical POSITION. A blocker entirely on one side of centre
- *  (a platform action rail) is a SIDE region — it caps the caption's horizontal
- *  corridor instead of blocking the whole row. This is what lets a centred
- *  caption sit at lower-third while a right rail only narrows/shifts it. */
-const straddlesCentre = (r) => r.x < CENTER && r.x + r.w > CENTER;
-/**
- * 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 function placeInLegalArea(el, b) {
-    const all = [...b.faceKeepOut, ...b.safeZones];
-    const bands = all.filter(straddlesCentre);
-    const sideRegions = all.filter((r) => !straddlesCentre(r));
-    // Blocked vertical spans from the band blockers only.
-    const spans = bands.map((r) => [r.y, r.y + r.h]).sort((a, c) => a[0] - c[0]);
-    const merged = [];
-    for (const s of spans) {
-        const last = merged[merged.length - 1];
-        if (last && s[0] <= last[1])
-            last[1] = Math.max(last[1], s[1]);
-        else
-            merged.push([s[0], s[1]]);
-    }
-    // Open vertical gaps within [0,1] that fit minH.
-    const gaps = [];
-    let cursor = 0;
-    for (const [a, c] of merged) {
-        if (a - cursor >= el.minH)
-            gaps.push([cursor, a]);
-        cursor = Math.max(cursor, c);
-    }
-    if (1 - cursor >= el.minH)
-        gaps.push([cursor, 1]);
-    if (gaps.length === 0)
-        return null;
-    // Anchor preference: top → highest gap; lower-third/bottom → lowest; free →
-    // tallest. (left/right collapse to the tallest gap in this band model.)
-    const pick = el.anchor === "top"
-        ? gaps[0]
-        : el.anchor === "free" || el.anchor === "left" || el.anchor === "right"
-            ? gaps.reduce((m, g) => (g[1] - g[0] > m[1] - m[0] ? g : m))
-            : gaps[gaps.length - 1];
-    // Bottom-anchored elements sit at the BOTTOM of their gap; others at the top.
-    const isBottom = el.anchor === "bottom" || el.anchor === "lower-third";
-    const y = isBottom ? pick[1] - el.minH : pick[0];
-    // Cap the horizontal corridor by side regions overlapping the chosen band.
-    let leftBound = 0;
-    let rightBound = 1;
-    for (const r of sideRegions) {
-        const overlapsBand = r.y < y + el.minH && r.y + r.h > y;
-        if (!overlapsBand)
-            continue;
-        if (r.x + r.w <= CENTER)
-            leftBound = Math.max(leftBound, r.x + r.w); // left rail
-        else if (r.x >= CENTER)
-            rightBound = Math.min(rightBound, r.x); // right rail
-    }
-    const avail = rightBound - leftBound;
-    const w = Math.min(avail, Math.min(0.92, Math.max(el.minW, 0.8)));
-    if (w < MIN_CAPTION_WIDTH)
-        return null; // corridor too narrow → no legal placement here
-    const x = leftBound + (avail - w) / 2; // centre within the available corridor
-    return { x, y, w, h: el.minH };
-}
-/**
- * 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 function resolveCaptionRegion(input) {
-    const sz = lookupSafeZones(input.platform ?? "", input.aspect);
-    const ext = input.captionExtent ?? { w: 0.8, h: 0.15 };
-    const region = placeInLegalArea({ id: "captions", anchor: input.anchor ?? "lower-third", minH: ext.h, minW: ext.w }, { faceKeepOut: [], safeZones: sz.exclusions });
-    // Captions are required → never dropped: forced band just above the safe strip.
-    return region ?? { x: 0.1, y: clamp01(1 - ext.h), w: ext.w, h: ext.h };
-}
-/**
- * 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 function resolveOverlayRegion(input) {
-    const sz = lookupSafeZones(input.platform ?? "", input.aspect);
-    const ext = input.extent ?? { w: 0.7, h: 0.35 };
-    const blockers = input.captionRegion ? [input.captionRegion] : [];
-    const region = placeInLegalArea({ id: "overlay", anchor: "free", minH: ext.h, minW: ext.w }, { faceKeepOut: [], safeZones: [...sz.exclusions, ...blockers] });
-    // No legal band (caption + chrome fill the frame) → a conservative upper band.
-    return region ?? { x: 0.1, y: clamp01((sz.exclusions.find((r) => r.y === 0)?.h ?? 0) + 0.02), w: 0.8, h: 0.3 };
-}
-// ── Legibility (worst-tile APCA over a supplied luminance summary; spec §6.3) ─
-const WHITE_POLE = "#FFFFFF";
-/**
- * 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 function decideLegibility(backdrop, textColor = WHITE_POLE) {
-    const textY = relativeLuminance(textColor);
-    const worst = backdrop.tiles.reduce((m, tileY) => Math.min(m, apcaLcFromLuminance(textY, tileY)), Number.POSITIVE_INFINITY);
-    if (worst >= CAPTION_LC_FLOOR)
-        return { lcTarget: CAPTION_LC_FLOOR, remedy: "none" };
-    return { lcTarget: CAPTION_LC_FLOOR, remedy: "scrim" };
-}
-// ── Top-level resolve (linear: keep-out → safe → yield → place → legibility) ─
-function sampleFrames(win, k = 5) {
-    const { startFrame: start, endFrame: end } = win;
-    const span = Math.max(0, end - start);
-    const n = Math.max(1, Math.min(k, span || 1));
-    if (n === 1)
-        return [start];
-    return Array.from({ length: n }, (_, i) => Math.round(start + (span * i) / (n - 1)));
-}
-function resolveOne(el, region, input) {
-    const legibility = el.hasText
-        ? decideLegibility(input.backdrop(region, sampleFrames(el.timeWindow)), el.textColor)
-        : { lcTarget: CAPTION_LC_FLOOR, remedy: "none" };
-    return { id: el.id, region, legibility };
-}
-/**
- * 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 function resolveCompositionFloor(input) {
-    const layout = resolveLayoutIntent(input.subjects);
-    const diagnostics = {
-        fallbacksTaken: [],
-        droppedElements: [],
-        matApplied: false,
-        layout,
-    };
-    // §22.2 — gate captions-behind-speaker. When the depth effect is requested AND
-    // eligibility signals are injected, an ineligible clip DEGRADES to a normal
-    // lower-third caption (effectiveDepthMode=false) — the caption is never dropped.
-    // Presence + band coverage gate here; the floor's own legibility invariant
-    // enforces visible-portion readability downstream, so legible=true at the gate.
-    let effectiveDepthMode = input.depthMode ?? false;
-    if (effectiveDepthMode && input.captionsBehind) {
-        const elig = captionsBehindEligible({
-            activeSpeakerPresenceFraction: input.captionsBehind.activeSpeakerPresenceFraction,
-            activeBandCoverage: input.captionsBehind.activeBandCoverage,
-            legible: true,
-        });
-        if (!elig.eligible) {
-            effectiveDepthMode = false;
-            diagnostics.fallbacksTaken.push(`captions-behind-ineligible:${elig.reason}`);
-        }
-    }
-    // 1) per-frame face keep-out + the clip-level box used for placement/yield.
-    //    speaker-switch: track the ACTIVE speaker (the crop follows them, so only
-    //    they're in frame); single-focus / static split: union every subject's face.
-    //    No face anywhere → conservative centre band.
-    const keepOutSeries = layout === "speaker-switch"
-        ? activeFaceKeepOutSeries(input.subjects, effectiveDepthMode)
-        : unionFaceKeepOutSeries(input.subjects, effectiveDepthMode);
-    const present = keepOutSeries.filter((r) => r !== null);
-    const clipKeepOut = present.length
-        ? boundingBox(present)
-        : { x: 0.3, y: 0.3, w: 0.4, h: 0.4 };
-    if (!present.length)
-        diagnostics.fallbacksTaken.push("no-face-center-band");
-    // static split/stacked still use the union (designed two-up geometry is a later
-    // plan); speaker-switch is now a designed path (active-speaker keep-out), not a
-    // fallback, so it isn't logged as one.
-    if (layout === "split" || layout === "stacked") {
-        diagnostics.fallbacksTaken.push(`multi-subject-union-placement:${layout}`);
-    }
-    // 2) safe zones for the destination.
-    const sz = lookupSafeZones(input.destination.platform, input.destination.aspect);
-    // 3) reframe FIRST, against the clip-max face extent. (Kills any feedback loop;
-    //    one stable stage.) depthMode (captions-behind) is a LATERAL constraint —
-    //    widen so the silhouette clears the centred caption; otherwise it's the
-    //    vertical band-yield for the tallest required (lower-third) element.
-    const requiredBand = Math.max(0, ...input.elements.filter((e) => e.required).map((e) => e.measuredExtent.h));
-    // captions-behind at the TOP anchor = the HERO composition (a big phrase above
-    // the subject — the "STEAL" look): open REAL top headroom (lower the subject +
-    // zoom, reframeYieldTop). center/lower-third behind = the existing lateral
-    // co-view body-bite. front = the vertical bottom-band yield. NO fake band: if
-    // a top hero caption can't get real headroom (head already frame-high),
-    // reframeYieldTop returns null → the treatment is wrong here, so DEGRADE to a
-    // readable lower-third FRONT caption (a top caption with no headroom would
-    // still occlude the face).
-    const captionEl = input.elements.find((e) => e.kind === "caption");
-    let effectiveElements = input.elements;
-    let reframe;
-    if (effectiveDepthMode && captionEl?.preferredRegion === "top") {
-        const topYield = reframeYieldTop({
-            maxFaceKeepOut: clipKeepOut,
-            neededBand: requiredBand,
-            aspect: input.destination.aspect,
-        });
-        if (topYield) {
-            reframe = topYield;
-        }
-        else {
-            effectiveDepthMode = false;
-            effectiveElements = input.elements.map((e) => e.kind === "caption" ? { ...e, preferredRegion: "lower-third" } : e);
-            diagnostics.fallbacksTaken.push("captions-behind-top-no-headroom");
-            reframe = reframeYield({
-                maxFaceKeepOut: clipKeepOut,
-                neededBand: requiredBand,
-                aspect: input.destination.aspect,
-            });
-        }
-    }
-    else if (effectiveDepthMode) {
-        reframe = coViewReframe(clipKeepOut);
-    }
-    else {
-        // Phase 4 (framing ownership): the plain non-depthMode CROP path no longer
-        // reframes — the renderer draws the agent's AUTHORED crop verbatim (the
-        // floor-vision fix; the agent owns framing, the floor doesn't doctor it).
-        // reframeYield stays for the depthMode→front degrade above (Phase 6 removes
-        // that branch with the rest of the captions-behind reframes).
-        reframe = { kind: "transform", dy: 0, zoom: 1 };
-    }
-    if (reframe.kind === "mat") {
-        diagnostics.matApplied = true;
-        diagnostics.fallbacksTaken.push("designed-mat");
-    }
-    // Apply the yield to the keep-out used for placement (raise/shrink mirrors the
-    // render transform). A mat reserves its band as an additional placement zone.
-    const placedKeepOut = reframe.kind === "transform"
-        ? [{ ...clipKeepOut, y: clamp01(clipKeepOut.y + reframe.dy), h: clipKeepOut.h * reframe.zoom }]
-        : [clipKeepOut];
-    const placementSafe = reframe.kind === "mat" ? [...sz.exclusions, reframe.rect] : sz.exclusions.slice();
-    // 4) place by priority. takeover ignores the face + inter-element (intentional
-    //    occlusion). required never drops; non-required drops + logs on no-fit.
-    const ordered = [...effectiveElements].sort((a, b) => b.priority - a.priority);
-    const perElement = [];
-    const taken = [];
-    for (const el of ordered) {
-        if (el.intent === "takeover") {
-            // Full-frame editorial card: occupies the safe area, honours only safe zones.
-            const region = { x: sz.titleSafe.x, y: sz.titleSafe.y, w: sz.titleSafe.w, h: sz.titleSafe.h };
-            perElement.push(resolveOne(el, region, input));
-            continue;
-        }
-        const region = placeInLegalArea({
-            id: el.id,
-            anchor: el.preferredRegion ?? "free",
-            minH: el.measuredExtent.h,
-            minW: el.measuredExtent.w,
-        }, { faceKeepOut: placedKeepOut, safeZones: [...placementSafe, ...taken] });
-        if (region) {
-            perElement.push(resolveOne(el, region, input));
-            taken.push(region);
-            continue;
-        }
-        // No legal slot.
-        if (el.required) {
-            // Guaranteed placement: the reserved mat band (yield already opened it), or
-            // a forced bottom band above the safe strip. Required is NEVER dropped.
-            const fallback = reframe.kind === "mat"
-                ? reframe.rect
-                : { x: 0.1, y: clamp01(1 - el.measuredExtent.h), w: 0.8, h: el.measuredExtent.h };
-            diagnostics.fallbacksTaken.push(`required-forced:${el.id}`);
-            perElement.push(resolveOne(el, fallback, input));
-            taken.push(fallback);
-        }
-        else {
-            diagnostics.droppedElements.push(el.id);
-        }
-    }
-    return { perElement, reframe, faceKeepOut: keepOutSeries, layout, diagnostics };
-}