@cueframe/kernel 0.0.1

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

@@ -0,0 +1,209 @@
+/**
+ * The card token contract, and the lint that enforces it at authoring time.
+ *
+ * A card's `tokens` map is projected to CSS custom properties by `cssLayoutVars`
+ * (./brandKit): key `x` becomes `--cf-x`, so the authored html must read it as
+ * `var(--cf-x)`. That one rule is the whole contract, and it was invisible on
+ * every agent-facing surface until 2026-08-05.
+ *
+ * WHY THIS EXISTS. A real session authored 65 cards binding `tokens: {"--p":
+ * …, "--f": …}` and reading them as `var(--p)` / `var(--f)`. Key `--p` projects
+ * to `--cf---p`, so `var(--p)` was undefined, and CSS "invalid at
+ * computed-value time" took over: `background: var(--p)` fell back to
+ * transparent (the plate vanished, leaving only its box-shadow as a dark
+ * smear) and `color: var(--f)` inherited black. `apply_composition` accepted
+ * all 65 silently and returned 86 bytes; the render succeeded; the USER was the
+ * first entity in the system to look at a pixel, 34 minutes and 3 renders in.
+ *
+ * ADVISORY only — same `(input) => string[]` contract as `detectNoAudioTrack`
+ * (../audio/mixStaging). Reading an undefined custom property is legal CSS and
+ * can be deliberate, so this never blocks an apply.
+ *
+ * KNOWN LIMIT: a `$brand:` token whose ref does not resolve is DROPPED by
+ * `cssLayoutVars`, so `var(--cf-x)` can still be undefined at render even when
+ * this lint passes. Catching that needs the org's resolved brand kit; the
+ * checks here are deliberately kit-free so they cost nothing (no extra read) on
+ * the apply path.
+ */
+// EXTENSIONLESS, and that is load-bearing rather than style. This module is
+// reachable from `projection/index.ts`, which the Remotion BUNDLE pulls in
+// (Root.tsx → MainComposition → OverlayContent → cssLayoutVars), and the bake's
+// webpack resolver has no `.js → .ts` substitution: a `./brandKit.js` here
+// resolves against nothing and fails the desktop build at `bake:remotion` —
+// AFTER a clean tsc and a clean vitest run, because neither uses that resolver.
+// Same class as the Lambda bundle's extensionless-import requirement. Every
+// other relative import in this directory is extensionless; match them.
+import { resolveBrandRefsDeep } from "./brandKit";
+/**
+ * The frame-driven vars `cardMotionVars` injects on EVERY card wrapper, on top
+ * of the token vars. SSOT for the names — `packages/execution/render-entry/src/components/
+ * cardMotion.ts` types its return against `CardMotionVarName`, so the two
+ * cannot drift. The lint must treat these as always-defined or every
+ * motion-authored card warns falsely.
+ */
+export const CARD_MOTION_VAR_NAMES = [
+    "--cf-frame",
+    "--cf-t",
+    "--cf-fps",
+    "--cf-duration",
+    "--cf-progress",
+    "--cf-ease",
+    "--cf-enter",
+    "--cf-exit",
+];
+/** `var(--name` — group 2 is "," when the reference supplies a fallback. */
+const VAR_REF = /var\(\s*(--[A-Za-z0-9_-]+)\s*(,?)/g;
+/** `--name:` — a custom property DECLARED in the card's own CSS. */
+const VAR_DECL = /(--[A-Za-z0-9_-]+)\s*:/g;
+/** How many distinct names to name in one advisory before eliding. */
+const MAX_NAMED = 8;
+/**
+ * Walk an arbitrary value tree and collect every card source in it. Structural
+ * rather than op-typed on purpose: cards reach `apply_composition` through
+ * `clip.add`, `clip.update` and `applyMotionPreset` alike, and a new op that
+ * carries one is linted the day it lands with no change here.
+ */
+function collectCards(value, nearestId, out) {
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectCards(v, nearestId, out);
+        return;
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    const obj = value;
+    // A clip carries `id`; its `source` does not. Track the closest one seen so
+    // the advisory can point at a clip rather than an ordinal.
+    const id = typeof obj.id === "string" ? obj.id : nearestId;
+    if (obj.kind === "card" && typeof obj.html === "string") {
+        const tokens = {};
+        if (obj.tokens !== null && typeof obj.tokens === "object") {
+            for (const [k, v] of Object.entries(obj.tokens)) {
+                if (typeof v === "string")
+                    tokens[k] = v;
+            }
+        }
+        out.push({ html: obj.html, tokens, ...(id !== undefined ? { id } : {}) });
+        return; // a card source never nests another card
+    }
+    for (const v of Object.values(obj))
+        collectCards(v, id, out);
+}
+const list = (names) => {
+    const all = [...names];
+    const shown = all.slice(0, MAX_NAMED).map((n) => `\`${n}\``).join(", ");
+    return all.length > MAX_NAMED ? `${shown} (+${all.length - MAX_NAMED} more)` : shown;
+};
+const cards = (n) => `${n} card clip${n === 1 ? "" : "s"}`;
+/**
+ * Lint every card in `value` (an ops array, a composition, a single clip — any
+ * shape) and return zero, one or two advisory strings.
+ *
+ * Two distinct defects, because they need different fixes:
+ *   `card_token_prefix`     — a tokens KEY that already starts with `--`, so it
+ *                             double-prefixes to `--cf---p`. Zero false
+ *                             positives; this is always a mistake.
+ *   `card_token_unresolved` — html reads `var(--x)` that nothing defines. Only
+ *                             fires when the name is not a `--cf-<tokens key>`,
+ *                             not a motion var, not declared in the card's own
+ *                             CSS, and the reference supplies no fallback.
+ */
+/**
+ * THE KIT-AWARE HALF, and the reason `detectUnresolvedCardTokens` cannot cover
+ * it. That lint is deliberately kit-free so it costs no extra read on the apply
+ * path, and its own header records the consequence: "a `$brand:` token whose ref
+ * does not resolve is DROPPED by `cssLayoutVars`, so `var(--cf-x)` can still be
+ * undefined at render even when this lint passes."
+ *
+ * That limit was cheap while every org had a brand kit. Signed out is now a
+ * SUPPORTED state with no kit at all, so it stopped being an edge: on
+ * 2026-08-16 every card in a composition rendered as unstyled black-on-nothing
+ * text — 16px, top-left, no background — because each token was a `$brand:` ref
+ * with nothing to resolve against, and nothing anywhere said so. The agent
+ * looking at those stills concluded the card renderer "strips inline styles".
+ *
+ * Given the kit that will actually be used, this reports the card tokens that
+ * will be DROPPED. Empty kit and empty result are different answers: a card with
+ * literal values is fine without a kit.
+ */
+export function detectDroppedBrandTokens(value, kit) {
+    const found = [];
+    collectCards(value, undefined, found);
+    if (found.length === 0)
+        return [];
+    const droppedKeys = new Set();
+    const droppedCards = new Set();
+    found.forEach((card, i) => {
+        const resolved = kit
+            ? resolveBrandRefsDeep(card.tokens, kit)
+            : card.tokens;
+        for (const [key, v] of Object.entries(resolved)) {
+            // `cssLayoutVars` emits a var only for a string that is no longer a ref;
+            // anything still `$brand:` is dropped, so `var(--cf-<key>)` is undefined.
+            if (typeof v === "string" && v.startsWith("$brand:")) {
+                droppedKeys.add(`--cf-${key}`);
+                droppedCards.add(card.id ?? `#${i + 1}`);
+            }
+        }
+    });
+    if (droppedKeys.size === 0)
+        return [];
+    return [
+        `card_brand_tokens_dropped — ${cards(droppedCards.size)} bind ${list(droppedKeys)} to a ` +
+            `\`$brand:\` reference that ${kit ? "this brand kit does not define" : "cannot resolve, because no brand kit is bound"}. ` +
+            `\`cssLayoutVars\` drops an unresolved ref, so those custom properties are absent at render and CSS ` +
+            `treats them as invalid at computed-value time: the card draws with browser defaults — 16px text, ` +
+            `transparent background — and looks like the styling was ignored. ` +
+            `${kit ? "Bind a key the kit defines" : "Bind a brand kit that defines them"}, or give each reference a ` +
+            `literal fallback: \`var(--cf-x, #fff)\`.`,
+    ];
+}
+export function detectUnresolvedCardTokens(value) {
+    const found = [];
+    collectCards(value, undefined, found);
+    if (found.length === 0)
+        return [];
+    const dashKeys = new Set();
+    const dashCards = new Set();
+    const missingVars = new Set();
+    const missingCards = new Set();
+    found.forEach((card, i) => {
+        const label = card.id ?? `#${i + 1}`;
+        const defined = new Set(CARD_MOTION_VAR_NAMES);
+        for (const key of Object.keys(card.tokens)) {
+            defined.add(`--cf-${key}`);
+            if (key.startsWith("--")) {
+                dashKeys.add(key);
+                dashCards.add(label);
+            }
+        }
+        // Custom properties the card declares for itself are satisfied by the card.
+        for (const m of card.html.matchAll(VAR_DECL))
+            defined.add(m[1]);
+        for (const m of card.html.matchAll(VAR_REF)) {
+            if (m[2] === ",")
+                continue; // `var(--x, fallback)` is a documented-legal pattern
+            if (defined.has(m[1]))
+                continue;
+            missingVars.add(m[1]);
+            missingCards.add(label);
+        }
+    });
+    const advisories = [];
+    if (dashKeys.size > 0) {
+        advisories.push(`card_token_prefix — ${cards(dashCards.size)} declare token key(s) ${list(dashKeys)} that ` +
+            `already begin with "--". A tokens key \`x\` is projected to the CSS custom property ` +
+            `\`--cf-x\`, so \`--p\` becomes \`--cf---p\` and the card's \`var(--p)\` resolves to ` +
+            `nothing. Drop the leading dashes — \`tokens: {"p": "#f00"}\` is read as \`var(--cf-p)\`.`);
+    }
+    if (missingVars.size > 0) {
+        advisories.push(`card_token_unresolved — ${cards(missingCards.size)} read ${list(missingVars)}, which ` +
+            `nothing defines: not a \`--cf-<tokens key>\`, not a card motion var, and not declared ` +
+            `in the card's own CSS. CSS treats an undefined custom property as "invalid at ` +
+            `computed-value time", so the property falls back silently — \`background\` to ` +
+            `transparent, \`color\` to inherited (usually black) — and the card renders broken ` +
+            `with no error. Bind it through \`tokens\` and read it as \`var(--cf-<key>)\`, or give ` +
+            `the reference a fallback: \`var(--x, #fff)\`.`);
+    }
+    return advisories;
+}

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

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