@cueframe/kernel 0.0.1

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

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