@cueframe/kernel 0.0.1 → 0.1.1

package/dist/_members/core/render/compositionRender.js

@@ -1,1249 +0,0 @@
-/**
- * Wire-shape `Composition` → `RenderInput` translator.
- *
- * `Composition` is the canonical multi-track wire shape from
- * `@cueframe/composition`. It crosses the API boundary
- * (PUT /v1/projects/:id/composition), gets snapshotted onto
- * `renderJobs.composition`, and is what the Remotion worker reads
- * before kicking off a render.
- *
- * This module is the single bridge from that wire shape to the
- * frame-based `RenderInput` Remotion consumes:
- *
- *   {format, tracks[]: [{kind, contents[]: TimelineClip[]}]}
- *      ↓
- *   compositionToRenderInput(composition, srcUrls)
- *      ↓
- *   { clips, overlays, audioTracks, effects, width, height, fps,
- *     durationInFrames }
- *
- * Track-kind handling:
- *   - `video` → `CompositionClip[]`. Each clip's wire startTime/duration
- *     map to timelineStartFrames/durationInFrames; `source.trim`'s
- *     source-relative seconds map to sourceInFrames/sourceOutFrames.
- *     Clips on multiple video tracks layer in track order (z-order
- *     follows the wire array).
- *   - `audio` → `CompositionAudioTrack[]`. `source.volumeDb` (if set)
- *     converts to linear gain via `10^(dB/20)`; `source.fadeInMs` /
- *     `source.fadeOutMs` convert to frames.
- *   - `image` → `CompositionClip[]` with `mediaType: 'image'`. Stills
- *     have no source timeline (sourceIn/Out are zero); `source.kenBurns`
- *     flows through as a convenience that the renderer's <StillCrop> lowers
- *     to a `reframe` (kenBurnsToReframe) and runs through the UNIFIED crop
- *     renderer, so a still gets the same per-frame point-zoom video does.
- *     Sub-frame durations are dropped (would crash Remotion's <Sequence>).
- *   - `overlay` → `CompositionOverlay[]`. Wire `source.primitiveId`
- *     becomes `template`; `source.params` flow through to the renderer.
- *   - `effect` → `CompositionEffect[]` with `target.kind: 'global'`,
- *     scoped to the effect clip's wire start/duration.
- *
- * `srcUrls` is a `mediaId → presigned URL` map. The caller (Temporal
- * activity) pre-signs every unique mediaId before calling this. A
- * referenced mediaId missing from `srcUrls` throws — silent fallbacks
- * are forbidden (the v0 path's silent-fallback bug class).
- */
-import { compositionHasVo, roleDefaultGainDb } from "@cueframe/composition/audio";
-import { flattenCompoundClips, hasCompoundClips } from "@cueframe/composition/timeline";
-import { resolveBookendTimeline } from "./bookends";
-/**
- * Project a wire clip's per-clip `effects` (authorable on `TimelineClip.effects`)
- * into clip-targeted render effects. The renderer's `EffectLayer` resolves
- * `target.kind==='clip'` by looking the `clipId` up in the clipFrames map (keyed
- * by render-clip id) and anchoring the effect to that clip's timeline window. We
- * target the FIRST emitted sub-span's render id (`renderClipId` — equals the wire
- * `c.id` for a single-span clip, `${c.id}#0` when excludedRanges fan it out) and
- * leave start/duration unset so `EffectLayer` spans the clip's whole window.
- *
- * Uses the SAME shape the global effect path (`projectEffectTrack`) emits — only
- * the `target` differs (`clip` vs `global`). When a clip carries no effects this
- * returns `[]`, so behavior is unchanged for the common case.
- */
-function projectClipEffects(clip, renderClipId) {
-    const effects = clip.effects;
-    if (!effects || effects.length === 0)
-        return [];
-    return effects.map((e, idx) => ({
-        // Deterministic, unique within the RenderInput: derives from the render-clip
-        // id + the effect's index on the clip (so React keys / clipFrames don't collide).
-        id: `${renderClipId}::effect:${idx}`,
-        primitiveId: e.primitiveId,
-        params: (e.params ?? {}),
-        target: { kind: "clip", clipId: renderClipId },
-    }));
-}
-/**
- * Resolve `Format` (`aspectRatio`, optional `fps` + `resolution`) to
- * concrete pixel dimensions. Mirrors the public-composition path's
- * `publicFormatDimensions` so a Composition with `format: { aspectRatio:
- * "9:16", fps: 30, resolution: "fhd" }` lands at the same 1080×1920
- * regardless of which translator the worker traversed.
- */
-export function compositionFormatDimensions(format) {
-    const fps = format.fps ?? 30;
-    const resolution = format.resolution ?? "fhd";
-    const dims = {
-        "9:16": {
-            hd: { width: 720, height: 1280 },
-            fhd: { width: 1080, height: 1920 },
-            "4k": { width: 2160, height: 3840 },
-        },
-        "1:1": {
-            hd: { width: 720, height: 720 },
-            fhd: { width: 1080, height: 1080 },
-            "4k": { width: 2160, height: 2160 },
-        },
-        "4:5": {
-            hd: { width: 720, height: 900 },
-            fhd: { width: 1080, height: 1350 },
-            "4k": { width: 2160, height: 2700 },
-        },
-        "16:9": {
-            hd: { width: 1280, height: 720 },
-            fhd: { width: 1920, height: 1080 },
-            "4k": { width: 3840, height: 2160 },
-        },
-    };
-    return { ...dims[format.aspectRatio][resolution], fps };
-}
-/**
- * Runtime-validate an untrusted value as a `Composition`. The Temporal
- * activity reads `renderJobs.composition` which is stored as
- * `v.optional(v.any())` — Convex doesn't enforce shape at read time. A
- * schema drift or a manual DB edit could leave a malformed value here,
- * and the renderer would crash later in the pipeline with a less
- * actionable error.
- *
- * Returns the validated composition or throws with a specific error
- * message. Call this at the activity boundary before passing the
- * composition to `compositionToRenderInput`. Pure JS validation — no
- * Zod runtime — so this module ships into the Temporal worker without
- * dragging the package's Zod surface along.
- */
-export function validateComposition(raw) {
-    if (!raw || typeof raw !== "object") {
-        throw new Error("composition: expected object, got " + typeof raw);
-    }
-    const obj = raw;
-    if (obj.v !== 1) {
-        throw new Error("composition.v: expected literal 1");
-    }
-    const fmt = obj.format;
-    if (!fmt || typeof fmt.aspectRatio !== "string") {
-        throw new Error("composition.format.aspectRatio: required string");
-    }
-    if (!Array.isArray(obj.tracks)) {
-        throw new Error("composition.tracks: expected array");
-    }
-    for (let i = 0; i < obj.tracks.length; i++) {
-        const t = obj.tracks[i];
-        if (!t || typeof t !== "object") {
-            throw new Error(`composition.tracks[${i}]: expected object`);
-        }
-        if (typeof t.id !== "string") {
-            throw new Error(`composition.tracks[${i}].id: expected string`);
-        }
-        if (!["video", "audio", "image", "overlay", "effect"].includes(t.kind)) {
-            throw new Error(`composition.tracks[${i}].kind: invalid value`);
-        }
-        if (!Array.isArray(t.contents)) {
-            throw new Error(`composition.tracks[${i}].contents: expected array`);
-        }
-    }
-    if (obj.markers !== undefined && !Array.isArray(obj.markers)) {
-        throw new Error("composition.markers: expected array when present");
-    }
-    if (obj.captions !== undefined) {
-        const c = obj.captions;
-        if (!c || typeof c !== "object") {
-            throw new Error("composition.captions: expected object when present");
-        }
-        // Captions are segment-structured ({ segments: [{ words }] }); the legacy flat
-        // `words` shape is gone. Validate the segments array the flatten below consumes.
-        if (!Array.isArray(c.segments)) {
-            throw new Error("composition.captions.segments: expected array");
-        }
-        if (c.style !== undefined && (typeof c.style !== "object" || c.style === null)) {
-            throw new Error("composition.captions.style: expected object when present");
-        }
-        // fontSize UNITS backstop — PERCENT of composition height, bounded [1,15]
-        // (the wire zod enforces the same bound at author time; this catches
-        // STORED/legacy compositions read back from `renderJobs.composition`,
-        // which is v.any()). A px-intent value (e.g. 31 — memoir/P2surf E2E
-        // 2026-07-22) would render 31% of the frame height per token: a giant
-        // multi-line page overflowing the caption band into the upper half. Fail
-        // loud at the render boundary rather than ship garbage pixels; this runs
-        // in resolveRenderEnvironment BEFORE the render cache is consulted, so a
-        // stale mis-sized MP4 is never served either.
-        if (c.style !== undefined) {
-            const fs = c.style.fontSize;
-            if (fs !== undefined && (typeof fs !== "number" || fs < 1 || fs > 15)) {
-                throw new Error("composition.captions.style.fontSize: PERCENT of composition height (1-15, default 5) — " +
-                    `got ${String(fs)}. px values are not accepted; a px-intent value renders giant ` +
-                    "band-overflowing captions. Re-author the style with a percent value.");
-            }
-        }
-    }
-    return obj;
-}
-/** Round non-negative seconds to a frame index. */
-function frames(seconds, fps) {
-    return Math.max(0, Math.round(seconds * fps));
-}
-/**
- * The frame span of a TIMELINE placement, ANCHORED AT BOTH ENDS.
- *
- * THE BUG THIS EXISTS FOR. Rounding `startTime` and `duration` INDEPENDENTLY —
- * `frames(start)` and `frames(duration)` — does not compose:
- *
- *     round(a·f) + round(d·f)  !==  round((a+d)·f)
- *
- * At 30fps a clip at 0.49s lasting 0.02s occupies frames 15..16, while the clip
- * authored to start exactly at 0.51s begins at frame 15 — a one-frame OVERLAP,
- * out of arithmetic alone. Shift the numbers slightly and it is a one-frame GAP
- * (a black flash). Two clips that are perfectly contiguous in seconds could
- * render as neither. The renderer already knew: the warm-decode grouping below
- * tolerates exactly this, "within one frame of rounding noise".
- *
- * Anchoring on the END TIME instead makes it compose by construction: clip A's
- * last frame is `frames(Aend)` and clip B starts at `frames(Bstart)`, so when
- * `Bstart === Aend` in seconds the two are the SAME integer and the boundary is
- * exact — no gap, no overlap, no tolerance needed.
- *
- * Every timeline placement goes through here. Source-time quantities
- * (`sourceInFrames`, trims, fades) keep using `frames()`: they are not spans on
- * the timeline and have no neighbour to meet.
- */
-function timelineSpanFrames(startSec, endSec, fps) {
-    const startFrame = frames(startSec, fps);
-    return { startFrame, durationInFrames: Math.max(0, frames(endSec, fps) - startFrame) };
-}
-/**
- * Map a canonical `Transition.type` (a free string the agent authors, e.g.
- * 'fade' | 'dissolve' | 'wipe' | 'cut' | 'push') to the render input's
- * supported presentation enum. 'cut' → 'none' (a hard cut needs no
- * presentation); anything the renderer can't present ('push'/'slide'/unknown)
- * falls back to 'fade' so the transition still appears rather than silently
- * dropping to dead pixels.
- */
-function mapTransitionType(type) {
-    switch (type) {
-        case 'fade':
-        case 'dissolve':
-        case 'wipe':
-        case 'none':
-            return type;
-        case 'cut':
-            return 'none';
-        default:
-            return 'fade';
-    }
-}
-/**
- * Overlay entrance-transition projection — mirrors the video-clip mapping at the
- * `s === 0` site in projectMediaTrack so an authored `transitionIn` on an
- * OVERLAY-family clip (alpha-layer / card / custom / primitive) is honored at
- * render. It was silently dropped: only the video lane projected these two
- * fields, so an authored overlay transition rendered as a dead hard cut (the v5
- * memoir "silent transitionIn drop" Class-B failure). Same field names/shape/enum
- * as the clip lane; the render host wraps the mounted overlay content in a
- * frame-pure entrance envelope when they are present, and emits nothing (=
- * byte-identical behavior) when absent.
- */
-function overlayTransitionFields(c, fps) {
-    return c.transitionIn
-        ? {
-            transitionIn: mapTransitionType(c.transitionIn.type),
-            transitionDurationFrames: Math.max(1, Math.round(c.transitionIn.duration * fps)),
-        }
-        : {};
-}
-/**
- * A clip that produces no frames, and therefore must not be able to fail a
- * render by demanding a URL it will never use.
- *
- * Five duplicate `duration: 0` clips of a cloud-only SFX took the whole app
- * down through the ErrorBoundary with "no presigned URL was supplied" — for
- * media that could never appear in the output. `durationInFrames` rounds to
- * zero and Remotion draws nothing either way; the only difference is whether
- * the render happens at all.
- *
- * ONE definition, because the video and image loops both need it and two
- * copies of one rule is how they drift.
- */
-function rendersNoFrames(c) {
-    return !(c.duration > 0);
-}
-function resolveSrcUrl(mediaId, srcUrls) {
-    const url = srcUrls[mediaId];
-    if (!url) {
-        throw new Error(`Composition references mediaId '${mediaId}' but no presigned URL was supplied. ` +
-            `Pre-sign every unique mediaId before calling compositionToRenderInput.`);
-    }
-    return url;
-}
-/**
- * Given a clip's effective trim window [trimStart, trimEnd] and an
- * optional sorted+non-overlapping list of excluded ranges (all in source
- * coordinates), return the playable spans in order. Each span is a
- * contiguous source range that should render as a sub-clip.
- *
- * Invariant (enforced upstream): Σ(span.end - span.start) === clip.duration.
- */
-/** The clip's playable spans (seconds) = [trimStart, trimEnd] minus
- *  excludedRanges. SSOT for section splitting — exported so the Director derives
- *  the SAME sections the render uses when it builds structure-first keep-outs. */
-export function playableSpans(trimStart, trimEnd, excluded) {
-    if (!excluded || excluded.length === 0) {
-        return [{ start: trimStart, end: trimEnd }];
-    }
-    const out = [];
-    let cursor = trimStart;
-    for (const r of excluded) {
-        if (r.start > cursor)
-            out.push({ start: cursor, end: r.start });
-        cursor = r.end;
-    }
-    if (cursor < trimEnd)
-        out.push({ start: cursor, end: trimEnd });
-    return out;
-}
-/**
- * Project a video/audio track's contents into `CompositionClip[]` /
- * `CompositionAudioTrack[]`. Clips on the wire reference media via
- * `source: { kind: 'media', mediaId, trim? }`; sources of any other
- * kind on a video/audio track are a wire violation and are dropped
- * with a thrown error.
- */
-function projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls) {
-    const clips = [];
-    const audio = [];
-    const effects = [];
-    for (let i = 0; i < track.contents.length; i++) {
-        const c = track.contents[i];
-        // Wire `Gap` entries omit `source`; render path drops them — gaps
-        // on the timeline are produced naturally by clip start/duration
-        // gaps. `Gap` only carries explicit non-contiguous semantics that
-        // matter to OTIO export, not to Remotion.
-        if (!("source" in c) || !c.source)
-            continue;
-        if (c.source.kind !== "media") {
-            throw new Error(`composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on a ${track.kind} track (expected 'media')`);
-        }
-        if (rendersNoFrames(c))
-            continue;
-        const src = resolveSrcUrl(c.source.mediaId, srcUrls);
-        // FAIL LOUD: a co-view clip (captions-behind-subject matte → packed scene)
-        // placed in a sub-frame `region` is unsupported — MainComposition's co-view
-        // z-split path renders the packed file full-frame and does NOT honor region,
-        // so the placement would be silently dropped (the card paints over the whole
-        // canvas). Reject at projection time rather than ship a mis-placed render.
-        if (coViewUrls?.[c.source.mediaId] !== undefined &&
-            c.region !== undefined &&
-            !(c.region.x === 0 && c.region.y === 0 && c.region.w === 1 && c.region.h === 1)) {
-            throw new Error(`composition.tracks[${track.id}].contents[${i}] (clip ${c.id}): a co-view ` +
-                `clip (captions-behind-subject) cannot also carry a sub-frame region — the ` +
-                `co-view render path does not honor region. Use one or the other.`);
-        }
-        if (track.kind === "audio") {
-            const trimStart = c.source.trim?.start ?? 0;
-            const trimEnd = c.source.trim?.end ?? trimStart + c.duration;
-            const spans = playableSpans(trimStart, trimEnd, c.source.excludedRanges);
-            // Audio mix: `volumeDb` (new for SFX beds) wins over the legacy
-            // linear `volume` field. dB → linear via 10^(dB/20). When neither
-            // is set, fall back to 1.0 (unchanged from source). The renderer
-            // separately defaults -12 dB for stock SFX selections; that's a
-            // policy decision applied upstream in the brief writer, not here.
-            // TRACK GAIN multiplies the clip's own level. It is a fader above the
-            // clips, not a replacement for them, so "turn the music down" is one
-            // control rather than an edit per clip — and an absent `track.volume`
-            // leaves the result bit-identical to before the field existed.
-            const resolvedVolume = (c.source.volumeDb !== undefined
-                ? Math.pow(10, c.source.volumeDb / 20)
-                : (c.source.volume ?? 1)) * (track.volume ?? 1);
-            // ms → frames. Round so fade-in + fade-out together never exceed
-            // the clip's duration (renderer's volume function would clamp, but
-            // we'd rather not rely on that).
-            const fadeInFrames = c.source.fadeInMs !== undefined
-                ? Math.max(0, Math.round((c.source.fadeInMs / 1000) * fps))
-                : undefined;
-            const fadeOutFrames = c.source.fadeOutMs !== undefined
-                ? Math.max(0, Math.round((c.source.fadeOutMs / 1000) * fps))
-                : undefined;
-            // Walk in accumulated SECONDS and derive each boundary end-anchored, so a
-            // sub-frame span that gets dropped cannot shift the ones after it (the old
-            // frame-cursor accumulation had to absorb that drift deliberately).
-            let playedSec = 0;
-            for (let s = 0; s < spans.length; s++) {
-                const span = spans[s];
-                const spanStartSec = c.startTime + playedSec;
-                playedSec += span.end - span.start;
-                const { startFrame, durationInFrames: subDurationFrames } = timelineSpanFrames(spanStartSec, c.startTime + playedSec, fps);
-                // Sub-frame spans (e.g. two excluded ranges leaving a 10ms gap at 30fps
-                // round to 0 frames) would crash Remotion's <Sequence>, which requires
-                // positive duration. Drop them — the dropped time is absorbed into the
-                // surrounding excluded zone. `playedSec` still advanced, so every LATER
-                // span keeps its true absolute position instead of sliding earlier.
-                if (subDurationFrames === 0)
-                    continue;
-                const sourceInFrames = frames(span.start, fps);
-                audio.push({
-                    id: spans.length === 1 ? c.id : `${c.id}#${s}`,
-                    src,
-                    sourceInFrames,
-                    sourceOutFrames: sourceInFrames + subDurationFrames,
-                    startFrame,
-                    durationInFrames: subDurationFrames,
-                    volume: resolvedVolume,
-                    ...(fadeInFrames !== undefined ? { fadeInFrames } : {}),
-                    ...(fadeOutFrames !== undefined ? { fadeOutFrames } : {}),
-                    ...(c.source.loop !== undefined ? { loop: c.source.loop } : {}),
-                });
-            }
-            continue;
-        }
-        const trimStart = c.source.trim?.start ?? 0;
-        // Fallback is in source coords — mirrors trimStart's scope. Don't replace
-        // with c.startTime + c.duration (timeline coords, dimensional mismatch).
-        const trimEnd = c.source.trim?.end ?? trimStart + c.duration;
-        const spans = playableSpans(trimStart, trimEnd, c.source.excludedRanges);
-        // First emitted sub-clip render id — the clip-targeted effect anchors to it
-        // (it's a key in EffectLayer's clipFrames map; the wire `c.id` itself is NOT
-        // when excludedRanges fan the clip into `${c.id}#N` sub-spans).
-        let firstEmittedSubId;
-        // Accumulated SECONDS, end-anchored per span — see the audio branch.
-        let playedSec = 0;
-        for (let s = 0; s < spans.length; s++) {
-            const span = spans[s];
-            const spanStartSec = c.startTime + playedSec;
-            playedSec += span.end - span.start;
-            const { startFrame: timelineCursorFrames, durationInFrames: subDurationFrames } = timelineSpanFrames(spanStartSec, c.startTime + playedSec, fps);
-            // See the audio branch above for the rationale: sub-frame spans
-            // would crash Remotion's <Sequence>. Skip them; `playedSec` has already
-            // advanced, so later spans keep their true absolute position.
-            if (subDurationFrames === 0)
-                continue;
-            const sourceInFrames = frames(span.start, fps);
-            // Stable sub-clip ID: deterministic across renders of the same composition,
-            // unique within the RenderInput so React keys don't collide. Single-span
-            // clips keep the original ID for backward compat with consumers that key
-            // on it (selection, hover, etc.).
-            const subId = spans.length === 1 ? c.id : `${c.id}#${s}`;
-            if (firstEmittedSubId === undefined)
-                firstEmittedSubId = subId;
-            clips.push({
-                id: subId,
-                src,
-                sourceInFrames,
-                sourceOutFrames: sourceInFrames + subDurationFrames,
-                timelineStartFrames: timelineCursorFrames,
-                durationInFrames: subDurationFrames,
-                // Clip-relative trajectory origin: every sub-span of this clip shares the
-                // clip's trim.start, so the crop can rebase source-absolute span frames
-                // to the clip-relative (trajectory) frame across the excludedRanges gaps.
-                trimStartFrames: frames(trimStart, fps),
-                ...(c.source.playbackRate !== undefined ? { playbackRate: c.source.playbackRate } : {}),
-                ...(c.source.volume !== undefined ? { volume: c.source.volume } : {}),
-                ...(c.source.muted !== undefined ? { muted: c.source.muted } : {}),
-                ...(c.source.loop !== undefined ? { loop: c.source.loop } : {}),
-                ...(c.opacity !== undefined ? { opacity: c.opacity } : {}),
-                ...(c.scale !== undefined ? { scale: c.scale } : {}),
-                ...(c.rotation !== undefined ? { rotation: c.rotation } : {}),
-                ...(c.animate !== undefined ? { animate: c.animate } : {}),
-                // Output-space placement. A sub-frame `region` makes the clip occupy
-                // only that rect of the output (PiP / split-screen / inset) — lower
-                // tracks show through the uncovered area. Carried per-clip (shared by
-                // every sub-span split from one wire clip). `fit` selects cover/contain.
-                ...(c.region !== undefined ? { region: c.region } : {}),
-                ...(c.fit !== undefined ? { fit: c.fit } : {}),
-                // Clip transition-in. Attached only to the FIRST span of a clip
-                // (transitions apply between original clips, not split sub-clips).
-                // The canonical `{type,duration}` maps to the render-input string enum
-                // + a frame count; without this the authored transition was dropped
-                // and rendered as a dead hard cut (mirror of tracksToRenderInput.ts).
-                ...(s === 0 && c.transitionIn
-                    ? {
-                        transitionIn: mapTransitionType(c.transitionIn.type),
-                        transitionDurationFrames: Math.max(1, Math.round(c.transitionIn.duration * fps)),
-                    }
-                    : {}),
-                // Per-frame crop trajectory URL. When present, the renderer
-                // applies the trajectory's per-frame normalized centers as a
-                // CSS transform over the raw video to produce the cropped
-                // output. Keyed by the PARENT wire-clip id `c.id` (NOT the
-                // sub-span `subId`): the trajectory map is per-clip (Phase 2), and
-                // every sub-span split from a clip shares that clip's trajectory.
-                // Resolved at the caller layer (Temporal activity), which looks up
-                // mediaItems.variants[intentHash][aspect].trajectoryR2Key per clip
-                // and presigns it.
-                ...(trajectoryUrls?.[c.id] !== undefined
-                    ? { cropTrajectoryUrl: trajectoryUrls[c.id] }
-                    : {}),
-                // Captions-behind CO-VIEW. Content-driven (Phase 6): the matte gate baked
-                // a crop-independent frame-packed co-view (scene over matte, one opaque
-                // H.264) for any clip whose timeline range overlaps a behind-subject
-                // caption window, surfaced here as coViewUrls[mediaId]. MATTE PRESENCE is
-                // the gate — no per-clip enable flag. The renderer splits the packed
-                // decode into the scene background + the subject cut-out foreground, and
-                // the global caption layer's behind tokens render between them (the
-                // output-space z-split in MainComposition).
-                ...(coViewUrls?.[c.source.mediaId] !== undefined
-                    ? { packedUrl: coViewUrls[c.source.mediaId] }
-                    : {}),
-            });
-        }
-        // Per-clip authored effects (target:'clip'). Anchored to the first emitted
-        // sub-clip render id (a clipFrames key). Skipped when every span dropped
-        // (sub-frame) so no effect targets a clip the renderer never mounted.
-        if (firstEmittedSubId !== undefined) {
-            effects.push(...projectClipEffects(c, firstEmittedSubId));
-        }
-    }
-    // Group consecutive runs sharing the same src + playbackRate on this
-    // track. Two distinct wire clips referencing the same mediaId — produced
-    // either by `cutAndRipple` splitting a clip into left/right fragments or
-    // by `excludedRanges` fanning one wire clip into N+1 sub-clips — share a
-    // parentId so MainComposition.groupClips collapses them into ONE
-    // <JumpCutVideo> driven by `sections`. Without this, each fragment
-    // mounts its own <Video> element and the user hits a cold network +
-    // decode warmup on every cut boundary.
-    for (let i = 1; i < clips.length; i++) {
-        const prev = clips[i - 1];
-        const cur = clips[i];
-        if (prev.src !== cur.src)
-            continue;
-        if ((prev.playbackRate ?? 1) !== (cur.playbackRate ?? 1))
-            continue;
-        // Different output placement → distinct on-screen rects; collapsing them
-        // into one <JumpCutVideo> would render both spans through clips[0]'s region.
-        // Sub-spans split from ONE wire clip copy the same region, so they still
-        // group (identical region → equal); only genuinely different placements split.
-        if (JSON.stringify(prev.region) !== JSON.stringify(cur.region))
-            continue;
-        if ((prev.fit ?? "cover") !== (cur.fit ?? "cover"))
-            continue;
-        // Per-clip crop trajectory + clip-relative origin must match. The merged
-        // group renders ALL its sections through ONE <CropFromTrajectory> driven by
-        // the FIRST clip's trajectory URL + trimStartFrames (MainComposition.GroupContent
-        // reads `first.cropTrajectoryUrl` / `first.trimStartFrames`). Two distinct wire
-        // reframe clips of the same media each carry their OWN trajectory (covering only
-        // their own clip-relative window) and their OWN trim.start — collapsing them
-        // would play the later clip's frames against the earlier clip's trajectory,
-        // overrunning its coverage by a few frames at the seam (the
-        // `trajectory_coverage_gap` bug: srcFrame past every segment). Sub-spans split
-        // from ONE wire clip (excludedRanges) share `c.id` → same trajectory URL → same
-        // trim.start, so they still merge into the warm-decode JumpCutVideo.
-        if (prev.cropTrajectoryUrl !== cur.cropTrajectoryUrl)
-            continue;
-        if ((prev.trimStartFrames ?? 0) !== (cur.trimStartFrames ?? 0))
-            continue;
-        // Consecutive on the timeline (within one frame of rounding noise).
-        const prevEnd = prev.timelineStartFrames + prev.durationInFrames;
-        if (Math.abs(prevEnd - cur.timelineStartFrames) > 1)
-            continue;
-        const parent = prev.parentId ?? prev.id;
-        cur.parentId = parent;
-        if (prev.parentId === undefined)
-            prev.parentId = parent;
-    }
-    return { clips, audio, effects };
-}
-/**
- * Project an image track's contents into `CompositionClip[]` with
- * `mediaType: 'image'`. Stills don't have a source timeline — `trim` /
- * `excludedRanges` are ignored. Each clip occupies the full duration on
- * the timeline; `kenBurns` flows through and the renderer's <StillCrop>
- * lowers it to a `reframe` for the unified per-frame crop.
- */
-function projectImageTrack(track, fps, srcUrls) {
-    const clips = [];
-    const effects = [];
-    for (let i = 0; i < track.contents.length; i++) {
-        const c = track.contents[i];
-        if (!("source" in c) || !c.source)
-            continue;
-        if (c.source.kind !== "media") {
-            throw new Error(`composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an image track (expected 'media')`);
-        }
-        if (rendersNoFrames(c))
-            continue;
-        const src = resolveSrcUrl(c.source.mediaId, srcUrls);
-        const { startFrame: timelineStartFrames, durationInFrames } = timelineSpanFrames(c.startTime, c.startTime + c.duration, fps);
-        // Sub-frame durations would crash Remotion's <Sequence>. Drop them
-        // the same way overlay/effect tracks do — the dropped time is
-        // implicit in the surrounding wire shape.
-        if (durationInFrames === 0)
-            continue;
-        clips.push({
-            id: c.id,
-            src,
-            // Stills have no source timeline — sourceIn/Out are zero. The
-            // renderer keys on mediaType==='image' to skip source-relative
-            // seeking entirely.
-            sourceInFrames: 0,
-            sourceOutFrames: 0,
-            timelineStartFrames,
-            durationInFrames,
-            mediaType: 'image',
-            kenBurns: c.source.kenBurns ?? 'in',
-            // The agent's authored camera channel for the still. When present it
-            // DRIVES the point-zoom (StillCrop derives the still trajectory from it);
-            // `kenBurns` is the fallback when no reframe was authored. This is how an
-            // image gets an arbitrary point-zoom (zoom into a UI element), not just
-            // the centered kenBurns presets.
-            ...(c.source.reframe !== undefined && c.source.reframe.segments.length > 0
-                ? { reframe: c.source.reframe }
-                : {}),
-            ...(c.opacity !== undefined ? { opacity: c.opacity } : {}),
-            ...(c.scale !== undefined ? { scale: c.scale } : {}),
-            ...(c.rotation !== undefined ? { rotation: c.rotation } : {}),
-            ...(c.animate !== undefined ? { animate: c.animate } : {}),
-            // Output-space placement (PiP / inset still). See projectMediaTrack.
-            ...(c.region !== undefined ? { region: c.region } : {}),
-            ...(c.fit !== undefined ? { fit: c.fit } : {}),
-        });
-        // Per-clip authored effects (target:'clip'). Image clips don't fan out, so
-        // the render-clip id is the wire `c.id`.
-        effects.push(...projectClipEffects(c, c.id));
-    }
-    return { clips, effects };
-}
-/** Clip-level transform channel (position/opacity/scale/rotation — the wire's
- *  "animation channel", distinct from the `region` placement primitive). One
- *  helper so all three overlay-family branches (overlay / card / alpha-layer)
- *  carry it identically — these fields were silently dropped here until
- *  2026-07-20 (spec §2.1.1). Absent stays absent: no defaults minted. */
-function clipTransformChannel(c) {
-    if (!("source" in c))
-        return {};
-    return {
-        ...(c.position !== undefined ? { position: c.position } : {}),
-        ...(c.opacity !== undefined ? { opacity: c.opacity } : {}),
-        ...(c.scale !== undefined ? { scale: c.scale } : {}),
-        ...(c.rotation !== undefined ? { rotation: c.rotation } : {}),
-        ...(c.animate !== undefined ? { animate: c.animate } : {}),
-    };
-}
-function projectOverlayTrack(track, fps, 
-/** clipId → baked-alpha file URL/path for alpha-layer clips (2.6b). The box
- *  bake writes the file + the daemon threads this map; absent for non-alpha. */
-alphaUrls = {}, 
-/** clipId → FRESH transpiled jsSource for component-backed `custom` overlays
- *  (bakeless live lane). Materialized per render from `installedComponents`
- *  (renders.ts) — the live-lane peer of `alphaUrls`, so a component edit is
- *  reflected on the next render with no re-save. Preferred over any stored
- *  `params.sourceCode` (which only desktop-INLINE customs carry). */
-jsSourceByClipId = {}) {
-    const overlays = [];
-    for (let i = 0; i < track.contents.length; i++) {
-        const c = track.contents[i];
-        if (!("source" in c) || !c.source)
-            continue;
-        // Alpha-layer (2.6b): an OWNED .cueframe component baked to a TRANSPARENT
-        // video (the component's props baked INTO the pixels — never run in the
-        // shared render). The render only needs the baked file + its zPlane. The
-        // file is resolved PER CLIP (alphaUrls[clipId]); the box bake produces it
-        // and the daemon threads the map. Missing ⇒ fail loud (never a silent
-        // empty layer): the bake must run before the render.
-        if (c.source.kind === "alpha-layer") {
-            const { startFrame, durationInFrames } = timelineSpanFrames(c.startTime, c.startTime + c.duration, fps);
-            if (durationInFrames === 0)
-                continue;
-            const src = alphaUrls[c.id];
-            if (!src) {
-                throw new Error(`composition.tracks[${track.id}].contents[${i}]: alpha-layer clip ${c.id} has no baked alpha (alphaUrls[${c.id}] missing) — bake before render`);
-            }
-            overlays.push({
-                id: c.id,
-                template: "alpha-layer",
-                startFrame,
-                durationInFrames,
-                params: { src },
-                ...(c.source.zPlane !== undefined ? { zPlane: c.source.zPlane } : {}),
-                ...(c.region !== undefined ? { region: c.region } : {}),
-                ...(c.fit !== undefined ? { fit: c.fit } : {}),
-                ...overlayTransitionFields(c, fps),
-                ...clipTransformChannel(c),
-            });
-            continue;
-        }
-        // card: an authored HTML/CSS graphic drawn VERBATIM by the wrapper
-        // (OverlayContent case 'card'). Carry the markup + brand-token map
-        // through untouched; brand refs resolve at the render boundary (like every
-        // overlay). The clip's `region` is the keep-out box. Front only this slice.
-        if (c.source.kind === "card") {
-            const { startFrame, durationInFrames } = timelineSpanFrames(c.startTime, c.startTime + c.duration, fps);
-            if (durationInFrames === 0)
-                continue;
-            overlays.push({
-                id: c.id,
-                template: "card",
-                startFrame,
-                durationInFrames,
-                params: {
-                    html: c.source.html,
-                    ...(c.source.tokens ? { cssTokens: c.source.tokens } : {}),
-                },
-                ...(c.source.zPlane !== undefined ? { zPlane: c.source.zPlane } : {}),
-                ...(c.region !== undefined ? { region: c.region } : {}),
-                ...(c.fit !== undefined ? { fit: c.fit } : {}),
-                ...overlayTransitionFields(c, fps),
-                ...clipTransformChannel(c),
-            });
-            continue;
-        }
-        if (c.source.kind !== "overlay") {
-            throw new Error(`composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an overlay track (expected 'overlay', 'alpha-layer', or 'card')`);
-        }
-        const { startFrame, durationInFrames } = timelineSpanFrames(c.startTime, c.startTime + c.duration, fps);
-        // Sub-frame durations would crash Remotion's <Sequence>. Drop the overlay.
-        if (durationInFrames === 0)
-            continue;
-        let overlayParams = (c.source.params ?? {});
-        // primitiveId="custom" — the DynamicOverlay/new Function sandbox lane. Its
-        // source resolves in one of two ways:
-        //  - component-backed (bakeless live lane): a FRESH per-clip jsSource from
-        //    `jsSourceByClipId` (materialized this render from installedComponents),
-        //    which WINS over any stored value so a component edit shows next render.
-        //  - desktop-INLINE: the transpiled code the author stored on
-        //    `params.sourceCode`.
-        // A custom with NEITHER would otherwise render "Custom graphic error: No
-        // sourceCode in params" into the frame (the in-loop judge scores that as
-        // editorial copy). This is the single render chokepoint every path passes
-        // through — fail loud, not a fallback. The component-reference marker
-        // (`params.componentId`) + any superseded stored source are stripped from the
-        // params handed to the sandbox, so the component sees only its own props.
-        if (c.source.primitiveId === "custom") {
-            const fresh = jsSourceByClipId[c.id];
-            const sc = typeof fresh === "string" && fresh.length > 0 ? fresh : overlayParams.sourceCode;
-            if (typeof sc !== "string" || sc.length === 0) {
-                throw new Error(`composition.tracks[${track.id}].contents[${i}].source: custom overlay has no sourceCode ` +
-                    `(no fresh jsSource for clip '${c.id}' and no inline params.sourceCode) — mirror code 'custom_missing_sourcecode'`);
-            }
-            const { componentId: _cid, sourceCode: _sc, ...props } = overlayParams;
-            void _cid;
-            void _sc;
-            overlayParams = { sourceCode: sc, ...props };
-        }
-        overlays.push({
-            id: c.id,
-            template: c.source.primitiveId,
-            startFrame,
-            durationInFrames,
-            params: overlayParams,
-            ...(c.source.zPlane !== undefined ? { zPlane: c.source.zPlane } : {}),
-            ...(c.source.anchor !== undefined ? { anchor: c.source.anchor } : {}),
-            ...(c.source.parallax !== undefined ? { parallax: c.source.parallax } : {}),
-            // Output-space placement (clip-level, like media/image): the overlay
-            // primitive occupies only this sub-rect of the output (PiP / inset card).
-            // MainComposition wraps it in the same RegionBox; absent = full frame.
-            ...(c.region !== undefined ? { region: c.region } : {}),
-            ...(c.fit !== undefined ? { fit: c.fit } : {}),
-            ...overlayTransitionFields(c, fps),
-            ...clipTransformChannel(c),
-        });
-    }
-    return overlays;
-}
-function projectEffectTrack(track, fps) {
-    const effects = [];
-    for (let i = 0; i < track.contents.length; i++) {
-        const c = track.contents[i];
-        if (!("source" in c) || !c.source)
-            continue;
-        if (c.source.kind !== "effect") {
-            throw new Error(`composition.tracks[${track.id}].contents[${i}]: kind=${c.source.kind} is invalid on an effect track (expected 'effect')`);
-        }
-        const { startFrame, durationInFrames } = timelineSpanFrames(c.startTime, c.startTime + c.duration, fps);
-        // Sub-frame durations would crash Remotion's <Sequence>. Drop the effect.
-        if (durationInFrames === 0)
-            continue;
-        effects.push({
-            id: c.id,
-            primitiveId: c.source.primitiveId,
-            params: (c.source.params ?? {}),
-            target: { kind: "global" },
-            startFrame,
-            durationInFrames,
-        });
-    }
-    return effects;
-}
-/**
- * Merge the composition's caption words into speech spans (gap < 300ms merges
- * adjacent words; spans < 200ms are dropped as noise), returned as ABSOLUTE
- * timeline frame ranges. This is the speech SSOT the duck envelope reads — it
- * ripples with every cut/ripple because caption words do.
- */
-function buildCaptionSpeechSpans(composition, fps) {
-    const words = (composition.captions?.segments ?? [])
-        .flatMap((seg) => seg.words)
-        .filter((w) => w.endMs > w.startMs)
-        .sort((a, b) => a.startMs - b.startMs);
-    if (words.length === 0)
-        return [];
-    const MERGE_GAP_MS = 300;
-    const MIN_SPAN_MS = 200;
-    const spans = [];
-    let cur = { startMs: words[0].startMs, endMs: words[0].endMs };
-    for (let i = 1; i < words.length; i++) {
-        const w = words[i];
-        if (w.startMs - cur.endMs < MERGE_GAP_MS) {
-            if (w.endMs > cur.endMs)
-                cur.endMs = w.endMs;
-        }
-        else {
-            spans.push(cur);
-            cur = { startMs: w.startMs, endMs: w.endMs };
-        }
-    }
-    spans.push(cur);
-    return spans
-        .filter((s) => s.endMs - s.startMs >= MIN_SPAN_MS)
-        .map((s) => ({
-        startFrame: Math.round((s.startMs / 1000) * fps),
-        endFrame: Math.round((s.endMs / 1000) * fps),
-    }));
-}
-/**
- * Role-based DEFAULT gain staging — a post-projection pass over the already-built
- * `audioTracks` (audio-substrate P0, Phase 3: "the engine owns the default mix").
- * It lives HERE, not in `projectMediaTrack`, because the music default is
- * CONDITIONAL on whether the WHOLE composition contains VO — track scope isn't
- * enough (same reason `applyDuckEnvelopes` is a post-projection pass).
- *
- * Rule: an authored `volumeDb`/`volume` ALWAYS wins (the projection already baked
- * it into `track.volume` at line ~362), so this only touches audio-track clips
- * whose source is role-tagged AND carries NEITHER authored level — it stamps the
- * calibrated ROLE_DEFAULT_GAIN_DB in its place. A clip with NO `audioRole` keeps
- * today's unity (the engine never guesses a role). This is the SINGLE default
- * point every render lane flows through (baked + live both call
- * `compositionToRenderInput`), so it can never diverge across lanes. AUDIO-only —
- * video-clip embedded audio is untouched (a VO video clip's default is 0 dB =
- * unity = the renderer's existing default, so there is nothing to change).
- */
-function applyRoleDefaultGains(audioTracks, composition) {
-    let voPresent;
-    for (const track of composition.tracks) {
-        if (track.kind !== "audio" || track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue; // skip Gaps
-            const src = c.source;
-            if (src.kind !== "media")
-                continue;
-            const role = src.audioRole;
-            if (!role)
-                continue; // no role → unity preserved (today's behaviour)
-            if (src.volumeDb !== undefined || src.volume !== undefined)
-                continue; // authored wins
-            // Resolve VO presence once, lazily (only when a role-tagged unauthored clip
-            // actually needs the music-conditional).
-            if (voPresent === undefined)
-                voPresent = compositionHasVo(composition);
-            const gain = Math.pow(10, roleDefaultGainDb(role, voPresent) / 20);
-            for (const t of audioTracks) {
-                if (t.id === c.id || t.id.startsWith(`${c.id}#`))
-                    t.volume = gain;
-            }
-        }
-    }
-}
-/**
- * Speech-window duck resolution — a post-projection pass over the already-built
- * `audioTracks`. It lives HERE (not in `projectMediaTrack`, which has no
- * `composition`/`captions` in scope — review correction A). For each audio clip
- * whose source carries `duck` and a `music`/`vo` role, resolve the speech windows
- * (from caption words, else the source's explicit `duck.windows`) into
- * SEQUENCE-RELATIVE frame ranges and stamp them onto the matching projected
- * track(s). Only `music`/`vo` roles duck; SFX (`audioRole:'sfx'`) and AMBIENCE
- * (`audioRole:'ambience'`) are NEVER ducked — ambience HOLDS under VO (founder
- * ruling, audio-substrate P0), so a stray `duck` on an ambience source is inert
- * here. Pure data → data.
- */
-function applyDuckEnvelopes(audioTracks, composition, fps) {
-    const captionSpansFrames = buildCaptionSpeechSpans(composition, fps);
-    for (const track of composition.tracks) {
-        if (track.kind !== "audio" || track.enabled === false)
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c))
-                continue; // skip Gaps (no source), same discrimination as the projection
-            const src = c.source;
-            if (src.kind !== "media")
-                continue;
-            const duck = src.duck;
-            const role = src.audioRole;
-            if (!duck || (role !== "music" && role !== "vo"))
-                continue;
-            // Explicit windows win when present; otherwise the caption-derived spans.
-            // The wire invariant forbids setting both (one SSOT) — enforced upstream.
-            const absWindows = duck.windows && duck.windows.length > 0
-                ? duck.windows.map((w) => ({
-                    startFrame: Math.round((w.startMs / 1000) * fps),
-                    endFrame: Math.round((w.endMs / 1000) * fps),
-                }))
-                : captionSpansFrames;
-            if (absWindows.length === 0)
-                continue;
-            const duckVolume = Math.pow(10, duck.duckDb / 20);
-            const attackFrames = Math.max(0, Math.round((duck.attackMs / 1000) * fps));
-            const releaseFrames = Math.max(0, Math.round((duck.releaseMs / 1000) * fps));
-            // Stamp every projected track derived from this clip (single span = `c.id`;
-            // excludedRange splits = `${c.id}#${s}`), clamping each window into the
-            // track's [0, durationInFrames] sequence-relative domain.
-            for (const t of audioTracks) {
-                if (t.id !== c.id && !t.id.startsWith(`${c.id}#`))
-                    continue;
-                const rel = [];
-                for (const w of absWindows) {
-                    const s = Math.max(0, w.startFrame - t.startFrame);
-                    const e = Math.min(t.durationInFrames, w.endFrame - t.startFrame);
-                    if (e > s)
-                        rel.push({ startFrame: s, endFrame: e });
-                }
-                if (rel.length === 0)
-                    continue;
-                t.duckWindows = rel;
-                t.duckVolume = duckVolume;
-                t.duckAttackFrames = attackFrames;
-                t.duckReleaseFrames = releaseFrames;
-            }
-        }
-    }
-}
-/**
- * Every unique mediaId the composition references — the SAME references
- * `compositionToRenderInput` resolves through `srcUrls` (any clip whose
- * `source.kind === 'media'`, on any track family). Interactive hosts (the
- * editor preview) gate on this BEFORE converting: a referenced id without a
- * URL yet is a LOADING state there, while the converter's fail-loud throw
- * stays correct for export/server paths where every URL must already exist.
- * Living next to the converter keeps the two walks from drifting.
- */
-export function referencedMediaIds(composition) {
-    const ids = new Set();
-    for (const track of composition.tracks) {
-        for (const c of track.contents) {
-            if (!("source" in c) || !c.source)
-                continue;
-            if (c.source.kind === "media" && typeof c.source.mediaId === "string") {
-                ids.add(c.source.mediaId);
-            }
-        }
-    }
-    return [...ids];
-}
-/**
- * Every component-REFERENCE `custom` overlay clip, as `clipId → componentId` —
- * the SAME references `compositionToRenderInput` resolves through
- * `jsSourceByClipId` (bakeless live lane). Clips carrying their own inline
- * `params.sourceCode` (desktop-authored customs) need no materialization and
- * are excluded. Interactive hosts (the editor preview) gate on this BEFORE
- * converting and feed the fetched live `jsSource`s in — the converter's
- * fail-loud `custom_missing_sourcecode` throw stays correct for export/server
- * paths. Living next to the converter keeps the walks from drifting.
- */
-export function componentRefsByClipId(composition) {
-    const refs = {};
-    for (const track of composition.tracks) {
-        if (track.kind !== "overlay")
-            continue;
-        for (const c of track.contents) {
-            if (!("source" in c) || !c.source)
-                continue;
-            const src = c.source;
-            if (src.kind !== "overlay" || src.primitiveId !== "custom")
-                continue;
-            const params = src.params ?? {};
-            if (typeof params.sourceCode === "string" && params.sourceCode.length > 0)
-                continue;
-            if (typeof params.componentId === "string" && params.componentId.length > 0) {
-                refs[c.id] = params.componentId;
-            }
-        }
-    }
-    return refs;
-}
-/**
- * Translate a wire-shape `Composition` to a frame-based `RenderInput`.
- *
- * The output's `durationInFrames` is the max content end across all
- * tracks (clips + overlays + effects). An empty composition produces
- * an empty RenderInput with duration 0 — caller decides whether that
- * should error or render a black frame; we don't make a policy call
- * here.
- */
-export function compositionToRenderInput(composition, srcUrls, 
-/**
- * Optional parallel map: `clipId → presigned crop-trajectory JSON URL`
- * (keyed PER CLIP since Phase 2 — two clips of one media with different
- * framing each carry their own trajectory). Populated by the caller
- * (Temporal activity) when the mediaItem has a baked variant for the
- * clip's window-qualified (intentHash, aspect). The renderer fetches the
- * JSON at composition time and applies a per-frame CSS transform on the
- * raw video to produce the cropped output. When unset for a given clipId,
- * the renderer plays the raw source un-cropped.
- */
-trajectoryUrls, 
-/**
- * Optional parallel map: `mediaId → presigned frame-packed co-view URL`
- * (scene over matte, one opaque H.264). Populated by the caller for any clip
- * whose timeline range overlaps a behind-subject caption window and whose
- * matte the gate baked (content-driven, Phase 6). Matte PRESENCE is the gate —
- * the render splits it into scene background + subject cut-out for the z-split.
- */
-coViewUrls, 
-/**
- * Optional parallel map: `clipId → baked-alpha file URL/path` for alpha-layer
- * clips (2.6b). The box bake (renderComponentAlpha) writes the transparent
- * video; the caller (session daemon / director) threads the path here. The
- * renderer mounts it as an alpha overlay at the clip's zPlane.
- */
-alphaUrls, 
-/**
- * Optional parallel map: `clipId → FRESH transpiled jsSource` for
- * component-backed `custom` overlays (bakeless live lane). Materialized per
- * render from `installedComponents` (renders.ts) — the live-lane peer of
- * `alphaUrls`. The overlay projection prefers it over any stored
- * `params.sourceCode`, so a component edit is reflected on the next render
- * with no composition re-save.
- */
-jsSourceByClipId, 
-/**
- * Compound-clip resolution: `compositionId → Composition` for every
- * `{kind:'composition'}` source the composition (transitively) embeds.
- * Flattening happens HERE, at the one translator every render lane flows
- * through, so an embedded sequence renders identically on desktop, cloud
- * and still lanes. A compound clip with no entry FAILS LOUD
- * (`compound_unresolved`) rather than rendering a deliverable that is
- * silently missing a sequence.
- */
-subCompositions) {
-    const flattened = hasCompoundClips(composition)
-        ? flattenCompoundClips(composition, (id) => subCompositions?.[id])
-        : composition;
-    composition = flattened;
-    const { width, height, fps } = compositionFormatDimensions(composition.format);
-    const clips = [];
-    const overlays = [];
-    const audioTracks = [];
-    const effects = [];
-    for (const track of composition.tracks) {
-        if (track.enabled === false)
-            continue;
-        if (track.kind === "video" || track.kind === "audio") {
-            const { clips: c, audio, effects: clipEffects } = projectMediaTrack(track, fps, srcUrls, trajectoryUrls, coViewUrls);
-            clips.push(...c);
-            audioTracks.push(...audio);
-            // Per-clip authored effects (target:'clip'), alongside the dedicated
-            // effect-track path (target:'global'). Both feed the one render effects[].
-            effects.push(...clipEffects);
-        }
-        else if (track.kind === "image") {
-            const { clips: c, effects: clipEffects } = projectImageTrack(track, fps, srcUrls);
-            clips.push(...c);
-            effects.push(...clipEffects);
-        }
-        else if (track.kind === "overlay") {
-            overlays.push(...projectOverlayTrack(track, fps, alphaUrls ?? {}, jsSourceByClipId ?? {}));
-        }
-        else if (track.kind === "effect") {
-            effects.push(...projectEffectTrack(track, fps));
-        }
-    }
-    // Role-based DEFAULT gain staging (Phase 3): stamp the calibrated engine
-    // default onto role-tagged audio clips that carry no authored level, BEFORE the
-    // duck pass (which layers a speech envelope on top of the base volume). Runs
-    // first so ducking operates on the correctly-staged base level. No-op unless a
-    // role-tagged clip lacks an authored volume.
-    if (audioTracks.length > 0) {
-        applyRoleDefaultGains(audioTracks, composition);
-    }
-    // Speech-aware ducking: resolve duck windows from caption words (SSOT) and
-    // stamp frame-range envelopes onto music/vo audio tracks. Post-projection so
-    // it has `composition.captions` in scope (correction A). No-op when no audio
-    // clip carries `duck`.
-    if (audioTracks.length > 0) {
-        applyDuckEnvelopes(audioTracks, composition, fps);
-    }
-    // durationInFrames covers the latest content edge across the whole
-    // timeline. Computed from the wire (not summed) so concurrent clips
-    // on stacked video tracks are handled correctly.
-    let maxEndFrames = 0;
-    const consider = (start, dur) => {
-        const end = start + dur;
-        if (end > maxEndFrames)
-            maxEndFrames = end;
-    };
-    for (const c of clips)
-        consider(c.timelineStartFrames, c.durationInFrames);
-    for (const o of overlays)
-        consider(o.startFrame, o.durationInFrames);
-    for (const a of audioTracks)
-        consider(a.startFrame, a.durationInFrames);
-    for (const e of effects) {
-        consider(e.startFrame ?? 0, e.durationInFrames ?? 0);
-    }
-    // VISUAL-DURATION CLAMP: caption lingers, decor-primitive overlays, audio
-    // tails, and effects must never extend the timeline past the last
-    // BACKGROUND-producing frame — frames beyond it have no source pixel and
-    // render solid black (waverly-final.mp4 2026-07-17: a ~2-frame black tail at
-    // 28.83-28.90s). Background-producing = video/image CLIPS **and SCENE-CLASS
-    // overlays** (alpha-layer / custom / card): a component world-layer or card IS
-    // the film's background in graphics-led and hybrid films. Without the
-    // scene-class term, a hybrid film whose background is a component overlay and
-    // whose only video clips are inset b-roll clamps to the b-roll's end and
-    // silently truncates (memoir-launch 41.5s → 6.9s, 2026-07-21). Decor
-    // primitive overlays (lower-thirds, badges) and caption pages still clamp —
-    // the original black-tail fix is preserved. When nothing background-producing
-    // exists, the overlay/effect edge legitimately defines the duration.
-    const SCENE_OVERLAY_TEMPLATES = new Set(["alpha-layer", "custom", "card"]);
-    let maxBackgroundEndFrames = 0;
-    for (const c of clips) {
-        const end = c.timelineStartFrames + c.durationInFrames;
-        if (end > maxBackgroundEndFrames)
-            maxBackgroundEndFrames = end;
-    }
-    for (const o of overlays) {
-        if (!SCENE_OVERLAY_TEMPLATES.has(o.template))
-            continue;
-        const end = o.startFrame + o.durationInFrames;
-        if (end > maxBackgroundEndFrames)
-            maxBackgroundEndFrames = end;
-    }
-    const bodyDurationInFrames = maxBackgroundEndFrames > 0 ? Math.min(maxEndFrames, maxBackgroundEndFrames) : maxEndFrames;
-    // Carry the authored caption SEGMENTS through (dropping empty ones); each
-    // segment is a hard caption-page boundary at render — the renderer paginates
-    // within a segment, never across — so sentence-bounded segments cut captions
-    // at sentence ends. Depth is overlay-only now (captions are FRONT-ONLY).
-    const captionSegments = composition.captions?.segments
-        .map((seg) => seg.words)
-        .filter((words) => words.length > 0);
-    // Frozen brand kit pass-through. The render snapshot
-    // (renderJobs.composition, see services/convex/api/internal/renders.ts)
-    // attaches the already-resolved brand kit at `composition.brandKit`.
-    // `Composition` is a `.passthrough()` schema so the field rides through
-    // untyped — read it back here so the renderer's primitive brand-resolution
-    // path is actually fed. Without this, RenderInput.brandKit is always
-    // undefined and brand-bound primitive defaults fall to their hardcoded
-    // `fallback`, producing off-brand output.
-    const brandKit = composition.brandKit;
-    // Brand BOOKENDS — when the resolved kit carries an intro/outro bumper, the
-    // render prepends the intro and appends the outro (MainComposition places +
-    // shifts the body); the composition total extends by intro+outro. fps-driven
-    // and SOFT (a missing/odd/srcless bumper reserves 0 frames → no extension).
-    const { totalFrames: durationInFrames } = resolveBookendTimeline(brandKit, bodyDurationInFrames, fps);
-    // Caption identity from the brand kit. Per-creator caption look is BRAND DATA:
-    // the resolved kit carries `caption.{ fg, fontFamily, emphasisFontFamily,
-    // emphasisScale, emphasisFontWeight, emphasisFontStyle }` (renders.ts →
-    // resolveBrandKit, derived from the dashboard / a creator's references). Here
-    // we build the caption style from that identity. Base GEOMETRY (size, screen
-    // position, safe-area) is NOT brand — it's the Captions primitive's calibrated
-    // DEFAULT_STYLE, which unset fields fall through to. So the kit selects the
-    // LOOK (serif-vs-sans emphasis, scale, weight, italic, accent); the primitive
-    // owns the legible realization.
-    //
-    // There is no caption VARIANT anymore — the old free-text-hint → variant
-    // picker is deleted. A clip with no kit rides the primitive default; a clip
-    // with a kit but no caption identity gets only the brand accent on the
-    // active/emphasis word (today's emphasisColor-only behavior, preserved).
-    //
-    // RenderInput's `brandKit` is typed against core's sparse BrandKit (no caption
-    // token), so the resolved-kit fields ride through untyped — read via a narrow
-    // accessor. An explicit per-clip `captions.style` override (rare) is the base
-    // the identity is applied over.
-    const cap = brandKit?.caption;
-    const brandAccent = cap?.fg ??
-        brandKit?.colors?.accent;
-    // Brand MOTION → caption entrance. Applied when the brand authored one of the
-    // caption-supported animated entrances ('fade' | 'word-pop' | 'stagger-up' —
-    // the shared TextMotion vocabulary the Captions primitive renders). A
-    // default/none/absent/unknown brand entrance leaves captions on the
-    // primitive's calibrated default (SOFT — never throws), so existing kits
-    // render identically. duration/staggerMs/exitMs ride the brand's values.
-    const mot = brandKit?.motion;
-    const ANIMATED_CAPTION_ENTRANCES = ["fade", "word-pop", "stagger-up"];
-    const captionEntrance = ANIMATED_CAPTION_ENTRANCES.includes(mot?.entrance)
-        ? mot.entrance
-        : undefined;
-    const captionMotion = captionEntrance
-        ? {
-            entrance: captionEntrance,
-            ...(mot.duration != null ? { entranceMs: mot.duration } : {}),
-            ...(mot.staggerMs != null ? { entranceStaggerMs: mot.staggerMs } : {}),
-            ...(mot.exitMs != null ? { exitMs: mot.exitMs } : {}),
-        }
-        : undefined;
-    const baseStyle = composition.captions?.style;
-    const hasCaptions = captionSegments != null && captionSegments.length > 0;
-    const captionStyle = hasCaptions && (cap || baseStyle || captionMotion)
-        ? {
-            ...(baseStyle ?? {}),
-            ...(cap?.fontFamily ? { fontFamily: cap.fontFamily } : {}),
-            ...(cap?.color ? { color: cap.color } : {}),
-            ...(cap?.plate ? { plate: cap.plate } : {}),
-            ...(cap?.emphasisFontFamily ? { emphasisFontFamily: cap.emphasisFontFamily } : {}),
-            ...(cap?.emphasisScale != null ? { emphasisScale: cap.emphasisScale } : {}),
-            ...(cap?.emphasisFontWeight != null ? { emphasisFontWeight: cap.emphasisFontWeight } : {}),
-            ...(cap?.emphasisFontStyle ? { emphasisFontStyle: cap.emphasisFontStyle } : {}),
-            ...(cap?.emphasisTextTransform ? { emphasisTextTransform: cap.emphasisTextTransform } : {}),
-            ...(cap?.emphasisLetterSpacing != null ? { emphasisLetterSpacing: cap.emphasisLetterSpacing } : {}),
-            ...(cap?.emphasisPlate != null ? { emphasisPlate: cap.emphasisPlate } : {}),
-            ...(cap?.emphasisPlateColor ? { emphasisPlateColor: cap.emphasisPlateColor } : {}),
-            ...(cap?.emphasisPlateTextColor ? { emphasisPlateTextColor: cap.emphasisPlateTextColor } : {}),
-            // Brand accent → active/emphasis word color (today's behavior); a
-            // creator-set caption highlightColor is caption-specific identity and
-            // WINS over the generic accent.
-            ...(brandAccent ? { highlightColor: brandAccent, emphasisColor: brandAccent } : {}),
-            ...(cap?.highlightColor ? { highlightColor: cap.highlightColor } : {}),
-            // Brand-motion-derived caption entrance is the generic fallback; a
-            // caption-specific entrance (cap.*) is identity and WINS, so it spreads
-            // AFTER captionMotion.
-            ...(captionMotion ?? {}),
-            ...(cap?.entrance ? { entrance: cap.entrance } : {}),
-            ...(cap?.entranceMs != null ? { entranceMs: cap.entranceMs } : {}),
-            ...(cap?.entranceStaggerMs != null ? { entranceStaggerMs: cap.entranceStaggerMs } : {}),
-            ...(cap?.exitMs != null ? { exitMs: cap.exitMs } : {}),
-        }
-        : undefined;
-    return {
-        clips,
-        overlays,
-        width,
-        height,
-        fps,
-        durationInFrames,
-        // Target platform (from the wire `Format`) frozen onto the render input so the
-        // composition floor's safe-zone placement clears that surface's UI chrome.
-        // Absent ⇒ the floor's 'unknown' (broadcast) default. Output-determining, so
-        // it's part of the render cache key (RENDER_CACHE_VERSION bumped alongside).
-        ...(composition.format.platform !== undefined ? { platform: composition.format.platform } : {}),
-        ...(audioTracks.length > 0 ? { audioTracks } : {}),
-        ...(effects.length > 0 ? { effects } : {}),
-        ...(hasCaptions ? { captionSegments } : {}),
-        ...(captionStyle ? { captionStyle } : {}),
-        ...(brandKit ? { brandKit } : {}),
-        // (fitMode deleted 2026-05-25 — baked variants replace render-time fit
-        // decisions; the chosen variant URL IS the framing.)
-    };
-}
-/**
- * Assemble a RenderInput from an ALREADY-validated (and brand-ref-resolved)
- * composition plus PRE-RESOLVED asset URL maps. This is the pure core shared by
- * the director's `resolveRenderEnvironment` (which resolves the URLs with R2/S3
- * creds, host-side) AND the in-container session daemon (which is handed the URLs
- * and holds no creds). One builder ⇒ render and capture cannot diverge on the
- * composition→RenderInput translation.
- *
- * `fontAssets` (when present) are the host-presigned brand font faces; they are
- * attached to the RenderInput's brandKit so the renderer can `@font-face` them.
- * The caller does the cred-bound URL/font resolution; this only assembles.
- */
-export function assembleRenderInput(composition, resolved) {
-    const renderInput = compositionToRenderInput(composition, resolved.srcUrls, resolved.trajectoryUrls ?? {}, resolved.coViewUrls ?? {}, resolved.alphaUrls ?? {}, resolved.jsSourceByClipId ?? {});
-    if (renderInput.brandKit && resolved.fontAssets && resolved.fontAssets.length > 0) {
-        renderInput.brandKit.fontAssets = resolved.fontAssets;
-    }
-    return renderInput;
-}