Skip to content

Open source CapCut alternative.

TypeScript
105 KB
Raw Blame
"use client";

import { captureRenderSnapshot, renderDoc, type ExportDoc, type RenderSnapshot } from "./renderSnapshot";
import { sourceExportPlan, sourceSequence } from "@/cut/lib/sourceExportPlan";
import { DELIVERY_DEFAULTS, EXPORT_PRESETS, EXPORT_RESOLUTIONS } from "./exportPresets";
import { operationFailure, type OperationFailure } from "./operationFailure";
import { UserError, errorFromBody, type UserErrorParams } from "./userError";
import { projectOperation } from "./projectOperation";

import { apiFetch, apiJson, getBackend, type CutBackend } from "./backend";
import { engineFeatures } from "./api";
import type { EngineFeature } from "./engineFeatures";
import { CUT_COLOR } from "./colorSettings";
import { CUT_EXPORT_PASSES } from "./exportPassSettings";
import { loadLibraryLutFile, lutIdOf } from "./linkedLibrary/luts";
import {
  removeBrowserExportJob,
  reserveBrowserExportJob,
  updateBrowserExportJob,
} from "./backend/browser/exportJobs";
import { deleteExport as dropStoredExport, exportsDir, projectDir, writeFileAt, readFileAt, saveExport } from "./backend/browser/opfs";
import { holdRegistered, registerBlobFile, releaseRegistered, resolveRegisteredBlob } from "./backend/browser/registry";
import { captureCloudBackend } from "./backend/cloud";
import { downloadFile, downloadFromUrl } from "./download";
import { bitrateFor, canRenderInBrowser, renderProjectToMp4, renderStemsArchive, type RenderedExport, type SourceExportProfile } from "./exportRender";
import { planStems, type StemDef } from "./stems";
import { putSigned } from "./media";
import { withAssetColors } from "./mediaRead";
import { renderRemovalPieces } from "./removalVideo";
import { renderCardPieces } from "./cameraCardVideo";
import { drawBlock } from "./blockSource";
import { createRasterCanvas, rasterCanvasToPng } from "./raster";
import { clipLen, clipSpeed, getClipSpans, MICRO_GAP_S, openedTimeline, overlayLayers, projectDuration, spanSequence, useEditor } from "./store";
import { captionStyle, cueOverlay, cueWordFrames, laneCues, laneHidden, subtitleLaneCount, trackPos } from "./subtitles";
import { drawStreak, elementLook, isMaskAnimated, isOverlayAnimated, matteLumaToAlpha, normalizeGrade, paintMaskLuma, paintStrokeInk, retimeOf, type EaseId, type FlashFade, type FlashRhythm, type FlashTone, type GlitchKind, type LeakCourse, type Mask, type SpeedNode } from "@donkeycut/effects-kit";
import { renderElementFrames, renderElementPng, renderStillPng, requireStickers } from "./textRender";
import { holdOverlays } from "./frameGrid";
import { CLIP_MIN_SECONDS, clipCovers, clipFrameAt, clipKeyed, clipPosed, clipPoseAt, clipZoom, contentRect, frameOf, isStickerOverlay, isTextOverlay, laneOf, overlayAnimStyle, projectBackground, rectOf, regionPx, removalActive, shadowInk, subjectMasked, parkedTimeline } from "./types";
import { liveReader } from "./liveReader";
import { soundSourceOf, spanSoundSpec, spanUsesSoundFeature, specSound } from "./soundSource";
import type {
  Aspect,
  AudioClip,
  ClipAnim,
  MediaAsset,
  Overlay,
  Selection,
  SubtitlesBlock,
  TimelineId,
  VideoClip,
} from "./types";

import {
  deliveryCodec,
  deliveryContainer,
  deliverySpan,
  EXPORT_CODECS,
  EXPORT_CONTAINERS,
  exportBaseName,
  fixedRate,
  STEMS_MIME,
  stemsArchiveName,
  type SpecClipColor,
  specMediaFiles,
  type ExportAudioCodec,
  type ExportCodec,
  type ExportContainer,
  type ExportRange,
} from "./exportDelivery";
export { deliveryCodec, EXPORT_CODECS, EXPORT_CONTAINERS, fixedRate };
export type { ExportAudioCodec, ExportCodec, ExportContainer, ExportRange };

export interface ExportSettings {
  /** Resolve the original media settings before starting an export. */
  matchSource?: boolean;
  /** Source delivery can preserve compatible encoded packets. */
  copySource?: boolean;
  width: number;
  height: number;
  fps: number;
  /** The quality tier, on x264's scale; the encoders that take a bitrate get
   * `bitrateFor` of it. */
  crf: number;
  preset: string;
  codec: ExportCodec;
  container: ExportContainer;
  audioCodec: ExportAudioCodec;
  /** Video bitrate in bits per second; omitted uses the quality tier. */
  bitrate?: number;
  /** AAC bitrate in bits per second; omitted uses the delivery default. */
  audioBitrate?: number;
  audioSampleRate?: number;
  audioChannels?: number;
  /** The file's name without its extension, as typed; absent = the project's
   * name. Sanitized by `exportBaseName` wherever a file is named. */
  name?: string;
  /** The stretch of the timeline to render, seconds; absent = all of it. */
  range?: ExportRange;
  /** The integrated loudness the mix is mastered to, LUFS; absent = the
   * mix as it plays. */
  loudness?: number;
  /** The true peak a mastered mix is held under, dBTP. */
  truePeakCeiling?: number;
  /** Write the audio as stems too: one WAV per lane, zipped beside the
   * video. */
  stems?: boolean;
}

export { DELIVERY_DEFAULTS, EXPORT_PRESETS } from "./exportPresets";

export const EXPORT_AUDIO = [
  { id: "aac", label: "AAC", detail: "compressed audio" },
  { id: "pcm", label: "PCM", detail: "uncompressed · MOV" },
] as const satisfies readonly { id: ExportAudioCodec; label: string; detail: string }[];

/** What a container can carry: the codec's own demand, and PCM's MOV. */
export function fitContainer(settings: ExportSettings): ExportSettings {
  const needed = deliveryCodec(settings.codec).container ?? (settings.audioCodec === "pcm" ? "mov" : null);
  if (needed && settings.container !== needed) return { ...settings, container: needed };
  return settings;
}

/** The file extension a setting's container takes. */
export function exportExtension(settings: Pick<ExportSettings, "container">): string {
  return deliveryContainer(settings.container).ext;
}


export const EXPORT_FRAME_RATES = [24, 30, 60] as const;

export const EXPORT_QUALITIES = [
  { id: "high", label: "High", detail: "best quality", crf: 19, preset: "medium" },
  { id: "balanced", label: "Balanced", detail: "smaller file", crf: 23, preset: "fast" },
  { id: "small", label: "Small", detail: "fastest render", crf: 28, preset: "veryfast" },
] as const;

export type ExportQualityId = (typeof EXPORT_QUALITIES)[number]["id"];

/** The user's whole choice, as the dialog holds it. */
export interface ExportChoice {
  sourceCodec?: boolean;
  /** A `resolutionOptions` id; one the project lacks falls back to "source". */
  resolution: string;
  /** A fixed rate, or "source" for the rate the footage plays at. */
  fps: number | "source";
  quality: ExportQualityId;
  codec: ExportCodec;
  container: ExportContainer;
  audioCodec: ExportAudioCodec;
  /** Megabits per second the user typed; absent = the tier. */
  bitrateMbps?: number;
}

/**
 * One-click exports. Each is a whole choice, so picking one sets every
 * advanced control at once, and the advanced panel shows what it stands for.
 */
export const EXPORT_QUICK_PRESETS = [
  {
    id: "share",
    label: "Share",
    detail: "1080p · plays everywhere",
    short: "1080p",
    choice: { resolution: "1080", fps: "source", quality: "balanced", ...DELIVERY_DEFAULTS },
  },
  {
    id: "best",
    label: "Best",
    detail: "original file settings",
    short: "Source",
    choice: { resolution: "source", fps: "source", quality: "high", sourceCodec: true, ...DELIVERY_DEFAULTS },
  },
  {
    id: "social4k",
    label: "Social 4K",
    detail: "4K upscale · platforms transcode it at a higher bitrate",
    short: "4K",
    choice: { resolution: "2160", fps: "source", quality: "high", ...DELIVERY_DEFAULTS },
  },
  {
    id: "small",
    label: "Small",
    detail: "720p · fastest",
    short: "720p",
    choice: { resolution: "720", fps: "source", quality: "small", ...DELIVERY_DEFAULTS },
  },
  {
    id: "master",
    label: "Master",
    detail: "ProRes 4444 · MOV · PCM · nothing given up",
    short: "ProRes",
    choice: { resolution: "source", fps: "source", quality: "high", codec: "prores4444", container: "mov", audioCodec: "pcm" },
  },
] as const satisfies readonly { id: string; label: string; detail: string; short: string; choice: ExportChoice }[];

/** The quick preset a choice is, when it is one. */
export function quickPresetOf(choice: ExportChoice, options: ResolutionOption[]): string | null {
  const key = (c: ExportChoice) =>
    [resolveResolution(options, c.resolution).id, c.fps, c.quality, c.codec, c.container, c.audioCodec, c.bitrateMbps ?? "", c.sourceCodec ?? false].join("|");
  const k = key(choice);
  return EXPORT_QUICK_PRESETS.find((p) => key(p.choice) === k)?.id ?? null;
}

/** The option a resolution id names, or the source frame when the project
 * has no such rung. */
export function resolveResolution(options: ResolutionOption[], id: string): ResolutionOption {
  return options.find((r) => r.id === id) ?? options.find((r) => r.id === "source") ?? options[0];
}

/** The rate an export runs at when the footage's own is not known: a cut of
 * stills and titles, or a source the probe could not read. */
export const DEFAULT_EXPORT_FPS = 30;

/** The settings a choice adds up to, with the container fitted to the codec
 * and audio it has to carry. `sourceFps` is the footage's rate (see
 * `sourceExportProfile`), what a "source" frame-rate choice resolves to. */
export function choiceSettings(
  choice: ExportChoice,
  options: ResolutionOption[],
  sourceFps: number = DEFAULT_EXPORT_FPS,
  sourceRates?: Partial<SourceExportProfile>
): ExportSettings {
  const q = EXPORT_QUALITIES.find((x) => x.id === choice.quality) ?? EXPORT_QUALITIES[0];
  const r = resolveResolution(options, choice.resolution);
  const settings = fitContainer({
    copySource: choice.resolution === "source" && choice.fps === "source" && choice.quality === "high" && !choice.bitrateMbps,
    width: r.width,
    height: r.height,
    fps: choice.fps === "source" ? sourceFps : choice.fps,
    crf: q.crf,
    preset: q.preset,
    codec: choice.sourceCodec ? sourceRates?.codec ?? choice.codec : choice.codec,
    container: choice.container,
    audioCodec: choice.audioCodec,
    // A fixed-rate codec has one rate per profile; a typed bitrate is for
    // the others.
    ...(choice.bitrateMbps && !fixedRate(choice.codec)
      ? { bitrate: Math.round(choice.bitrateMbps * 1_000_000) }
      : {}),
  });
  return choice.resolution === "source" && !choice.bitrateMbps
    ? matchSourceBitrates(settings, sourceRates)
    : settings;
}

/** Source-size delivery keeps the source's compression budget. */
export function matchSourceBitrates(
  settings: ExportSettings,
  source?: Partial<SourceExportProfile>
): ExportSettings {
  if (fixedRate(settings.codec)) return settings;
  return {
    ...settings,
    ...(source?.audioSampleRate ? { audioSampleRate: source.audioSampleRate } : {}),
    ...(source?.audioChannels ? { audioChannels: source.audioChannels } : {}),
    ...(source?.videoBitrate && Number.isFinite(source.videoBitrate) && source.videoBitrate > 0
      ? { bitrate: Math.round(settings.copySource ? source.videoBitrate : Math.min(bitrateFor(settings), source.videoBitrate)) } : {}),
    ...(settings.audioCodec === "aac" && source?.audioBitrate && Number.isFinite(source.audioBitrate) && source.audioBitrate > 0
      ? { audioBitrate: Math.round(settings.copySource ? source.audioBitrate : Math.min(audioBitrate(settings), source.audioBitrate)) } : {}),
  };
}

/** Apply a probed source profile to an original-settings export. */
export function matchSourceSettings(settings: ExportSettings, source: SourceExportProfile): ExportSettings {
  return matchSourceBitrates({ ...settings, matchSource: false, fps: source.fps ?? settings.fps, codec: source.codec ?? settings.codec }, source);
}

/** A size the dialog offers: the source's own frame, or a named rung above
 * or below it. */
export interface ResolutionOption {
  id: string;
  label: string;
  width: number;
  height: number;
  /** The rung is bigger than the footage: the render scales the picture up.
   * Platforms transcode a 4K upload on a higher bitrate rung than a 1080p
   * one, so an upscale can come back looking sharper than the source file
   * would have. */
  upscale?: boolean;
}

/**
 * The sizes this project can be exported at, largest first.
 *
 * "Source" is the frame the footage justifies. The named rungs below it are
 * the ones genuinely smaller; the ones above it are upscales, marked as such.
 * A rung that matches the source would be the same render under a second
 * name, so it is left out.
 */
export function resolutionOptions(
  aspect: Aspect,
  clips: VideoClip[],
  assets: MediaAsset[],
  composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): ResolutionOption[] {
  const src = sourceFrame(aspect, clips, assets, composition);
  const srcShort = Math.min(src.width, src.height);
  const rung = (r: (typeof EXPORT_RESOLUTIONS)[number]): ResolutionOption => ({
    id: r.id,
    label: r.label,
    ...scaledFrame(aspect, r.shortSide),
    ...(r.shortSide > srcShort ? { upscale: true } : {}),
  });
  return [
    ...EXPORT_RESOLUTIONS.filter((r) => r.shortSide > srcShort).map(rung),
    { id: "source", label: "Source", ...src },
    ...EXPORT_RESOLUTIONS.filter((r) => r.shortSide < srcShort).map(rung),
  ];
}

/**
 * The stretch of the timeline the selection covers: from the first selected
 * item's start to the last one's end, whatever rows they sit on. Null when
 * nothing with a place in time is selected.
 */
export function selectionRange(s: {
  multiSelection: Selection[];
  clips: VideoClip[];
  audioClips: AudioClip[];
  overlays: Overlay[];
  subtitles: SubtitlesBlock;
}): ExportRange | null {
  let start = Infinity;
  let end = -Infinity;
  const take = (a: number, b: number) => {
    start = Math.min(start, a);
    end = Math.max(end, b);
  };
  for (const sel of s.multiSelection) {
    if (!sel) continue;
    if (sel.kind === "clip") {
      const c = s.clips.find((x) => x.id === sel.id);
      if (c) take(c.start, c.start + clipLen(c));
    } else if (sel.kind === "audio") {
      const a = s.audioClips.find((x) => x.id === sel.id);
      if (a) take(a.start, a.start + clipLen(a));
    } else if (sel.kind === "overlay") {
      const o = s.overlays.find((x) => x.id === sel.id);
      if (o) take(o.start, o.end);
    } else if (sel.kind === "cue") {
      const c = s.subtitles.cues.find((x) => x.id === sel.id);
      if (c) take(c.start, c.end);
    }
  }
  return end > start ? { start, end } : null;
}

/** Frame dims for an aspect scaled to a short-side target, even-rounded. */
function scaledFrame(aspect: Aspect, shortSide: number): { width: number; height: number } {
  const f = frameOf(aspect);
  const k = shortSide / Math.min(f.w, f.h);
  const even = (n: number) => 2 * Math.round((n * k) / 2);
  return { width: even(f.w), height: even(f.h) };
}

export function presetSettings(
  preset: (typeof EXPORT_PRESETS)[number],
  aspect: Aspect
): ExportSettings {
  return { ...scaledFrame(aspect, preset.shortSide), ...preset.settings };
}

/**
 * Plain source sequences keep their original frame. Compositions fit the
 * project aspect, capped at 4K.
 * Projects with no measured source dimensions use the base frame.
 */
export function originalSettings(
  aspect: Aspect,
  clips: VideoClip[],
  assets: MediaAsset[],
  composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): ExportSettings {
  return { ...sourceFrame(aspect, clips, assets, composition), copySource: true, matchSource: true, fps: 30, crf: 19, preset: "medium", ...DELIVERY_DEFAULTS };
}

/** The frame `originalSettings` renders at — see its note for the rules. */
export function sourceFrame(
  aspect: Aspect,
  clips: VideoClip[],
  assets: MediaAsset[],
  composition?: Pick<ExportDoc, "audioClips" | "overlays" | "subtitles">
): { width: number; height: number } {
  const source = composition && sourceSequence({ aspect, clips, assets, ...composition })?.[0];
  if (source) return { width: source.asset.width!, height: source.asset.height! };
  const base = frameOf(aspect);
  const longBase = Math.max(base.w, base.h);
  const sourceScale = Math.max(
    0,
    ...getClipSpans(clips, assets).map((sp) =>
      Math.max((sp.asset.width ?? 0) / base.w, (sp.asset.height ?? 0) / base.h)
    )
  );
  const k = Math.min(3840 / longBase, sourceScale || 1);
  const even = (n: number) => Math.max(2, 2 * Math.round((n * k) / 2));
  return { width: even(base.w), height: even(base.h) };
}

/**
 * Rough output size for a setting, in bytes: the video bitrate the encoders
 * are given (`bitrateFor`) plus the selected audio bitrate. A CRF encode
 * spends what the footage needs, so busy footage runs larger and flat footage
 * smaller; the dialog shows it as an approximation.
 */
export function estimateExportBytes(settings: ExportSettings, durationSec: number): number {
  if (durationSec <= 0) return 0;
  return ((bitrateFor(settings) + audioBitrate(settings)) * durationSec) / 8;
}

/** AAC follows its source budget or uses 192 kbps; PCM is 48 kHz stereo 16-bit. */
export function audioBitrate(settings: Pick<ExportSettings, "audioCodec" | "audioBitrate" | "audioSampleRate" | "audioChannels">): number {
  return settings.audioCodec === "pcm" ? (settings.audioSampleRate ?? 48_000) * 16 * (settings.audioChannels ?? 2) : settings.audioBitrate ?? 192_000;
}

/** Human-readable size estimate matching the finished-export MB display,
 * with the number and unit in the reader's locale ("~1.4 MB", "~1,4 Mo"). */
export function formatSizeEstimate(bytes: number, locale: string): string {
  if (bytes <= 0) return "";
  const mb = bytes / (1024 * 1024);
  const size = (value: number, unit: "megabyte" | "gigabyte", digits: number) =>
    `~${new Intl.NumberFormat(locale, { style: "unit", unit, minimumFractionDigits: digits, maximumFractionDigits: digits }).format(value)}`;
  if (mb < 1) return size(1, "megabyte", 0);
  if (mb < 1000) return mb < 10 ? size(mb, "megabyte", 1) : size(Math.round(mb), "megabyte", 0);
  return size(mb / 1024, "gigabyte", 1);
}

/** Reveal a rendered export in Finder (local engine only). */
export async function revealExport(
  projectId: string,
  file: string,
  backend: CutBackend = getBackend()
) {
  await backend.fetch(
    `/api/cut/projects/${projectId}/exports/${encodeURIComponent(file)}/reveal`,
    { method: "POST" }
  );
}

/** A finished export's file, by name and modification time.
 *
 * The time is part of the URL. An export name comes free again when its file
 * is deleted, and the next render under that name lands on the same path, so
 * a URL of the path alone would answer with whatever the browser and the edge
 * still hold from the earlier file. The time changes with every render, so
 * each one has a URL of its own. */
export function exportFileUrl(projectId: string, item: { file: string; mtime: number }): string {
  return getBackend().url(
    `/api/cut/projects/${projectId}/exports/${encodeURIComponent(item.file)}?v=${item.mtime}`
  );
}

/** Download a rendered export — what stands in for revealExport when the
 * backend has no Finder (the cloud route 302s to a signed R2 URL). */
export function downloadProjectExport(projectId: string, item: { file: string; mtime: number }) {
  downloadFromUrl(exportFileUrl(projectId, item), item.file);
}

/** Delete a rendered export from the project folder. Throws on failure so the
 * UI can stay truthful instead of optimistically dropping a file that's still
 * on disk (which is why deleted exports used to reappear on the next refresh). */
export async function deleteExport(projectId: string, file: string) {
  const res = await apiFetch(
    `/api/cut/projects/${projectId}/exports/${encodeURIComponent(file)}`,
    { method: "DELETE" }
  );
  if (!res.ok) {
    const body = (await res.json().catch(() => ({}))) as { error?: string };
    throw errorFromBody(body, new UserError("export_delete_failed", "Could not delete the export."));
  }
}

/** The neutral built cut: the engine spec plus the browser-rendered overlay
 * PNGs. The local path serializes it to the engine's multipart form; the
 * cloud path presigns the PNGs to R2 and posts the spec as JSON. */
export interface ExportPayload {
  spec: object;
  pngs: { name: string; blob: Blob }[];
}

/** A masked video clip's coverage in the spec: one grayscale still, a
 * sampled sequence when the mask is keyframed, or the shared person matte
 * (`subject`) with its knobs. */
interface SpecMask {
  file?: string;
  frames?: { file: string; duration: number }[];
  subject?: { invert?: boolean; feather?: number };
}

/** How often a keyframed clip mask samples — the person-matte cadence; the
 * server re-stamps the output fps over it. */
const MASK_SAMPLE_FPS = 15;

/** The rate a moving mask samples at: the matte cadence, or the export's own
 * frame rate for a mask keyed more densely than that. A tracked outline
 * moves on every frame, and a coarser sample would step behind the hand. */
const maskSampleFps = (mask: Mask | undefined, dur: number, fps: number) =>
  (mask?.kf?.length ?? 0) / Math.max(dur, 1e-3) > MASK_SAMPLE_FPS ? Math.max(fps, MASK_SAMPLE_FPS) : MASK_SAMPLE_FPS;

/** Paint a clip's mask coverage for its export segment: one luma PNG for a
 * resting mask, a 15fps sampled sequence for a keyframed one. Keyframed
 * opacity folds into the luma — a clip fading under its pose track exports
 * an opacity-scaled coverage (flat white when it has no shape mask), so the
 * graph never needs an animatable alpha filter. The pictures land in `pngs`
 * and the returned entry references them by name. */
async function renderClipMaskPictures(
  clip: VideoClip,
  box: { x: number; y: number; w: number; h: number },
  W: number,
  H: number,
  dur: number,
  fps: number,
  tag: string,
  pngs: ExportPayload["pngs"]
): Promise<SpecMask | undefined> {
  const m = clip.mask && clip.mask.kind !== "subject" ? clip.mask : undefined;
  const opacityVaries = (clip.kf ?? []).some((k) => Math.abs(k.opacity - 1) > 1e-3);
  const radius = clip.boxStyle?.radius ?? 0;
  if (!m && !opacityVaries && radius <= 0) return undefined;
  const rect = rectOf(clip);
  const anchor = { x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 };
  const frame = { width: W, height: H, scale: Math.min(W, H) / 1080 };
  // Rounded corners trim coverage at the clip's box: outside the rounded box
  // everything drops, and inside it the mask keeps deciding.
  const rp = regionPx(clip.frame, W, H);
  const rb = rp
    ? { x: rp.rx - box.x, y: rp.ry - box.y, w: rp.rw, h: rp.rh }
    : { x: -box.x, y: -box.y, w: W, h: H };
  const canvas = createRasterCanvas(box.w, box.h);
  const blobAt = (tLocal: number) => {
    const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
    if (radius > 0) {
      ctx.globalCompositeOperation = "source-over";
      ctx.fillStyle = "#000000";
      ctx.fillRect(0, 0, canvas.width, canvas.height);
      ctx.save();
      ctx.beginPath();
      ctx.roundRect(rb.x, rb.y, rb.w, rb.h, radius * frame.scale);
      ctx.clip();
    }
    if (m) {
      paintMaskLuma(canvas, m, tLocal, frame, anchor, box.x, box.y);
    } else {
      ctx.globalCompositeOperation = "source-over";
      ctx.fillStyle = "#ffffff";
      ctx.fillRect(0, 0, canvas.width, canvas.height);
    }
    if (radius > 0) ctx.restore();
    if (opacityVaries) {
      const v = Math.round(
        255 * Math.max(0, Math.min(1, clipPoseAt(clip, tLocal).opacity))
      );
      ctx.globalCompositeOperation = "multiply";
      ctx.fillStyle = `rgb(${v},${v},${v})`;
      ctx.fillRect(0, 0, canvas.width, canvas.height);
      ctx.globalCompositeOperation = "source-over";
    }
    return rasterCanvasToPng(canvas);
  };
  if (!(m && isMaskAnimated(m)) && !opacityVaries) {
    const name = `${tag}.png`;
    pngs.push({ name, blob: await blobAt(0) });
    return { file: name };
  }
  const rate = maskSampleFps(m, dur, fps);
  const step = 1 / rate;
  const n = Math.max(1, Math.round(dur * rate));
  const frames: { file: string; duration: number }[] = [];
  for (let i = 0; i < n; i++) {
    const name = `${tag}_f${i}.png`;
    pngs.push({ name, blob: await blobAt(i * step) });
    frames.push({ file: name, duration: i === n - 1 ? Math.max(step, dur - (n - 1) * step) : step });
  }
  return { frames };
}

/** The keyed silhouette a removal clip's shadow falls from: white coverage
 * over transparency in the clip's source frame, sampled at a shadow frame's
 * local second. Null means the shadow keeps the picture's rectangle — no
 * active removal, a backdrop fill restoring the full picture, or an AI
 * removal whose matte hasn't baked (the export shows the plain picture then,
 * and a rectangular shadow matches it). */
function removalShadowSilhouette(
  clip: VideoClip,
  assets: MediaAsset[]
): { at: (tLocal: number) => Promise<CanvasImageSource | null>; dispose: () => void } | null {
  const r = clip.removal;
  if (!removalActive(r)) return null;
  if (r!.backdrop && r!.backdrop.kind !== "none") return null;
  const asset = assets.find((a) => a.id === clip.assetId);
  if (!asset) return null;
  const rt = retimeOf(clip);
  const still = asset.type === "image";
  const canvas = createRasterCanvas(2, 2);
  const ctx = canvas.getContext("2d", {
    willReadFrequently: true,
  }) as CanvasRenderingContext2D | null;
  if (!ctx) return null;
  const stage = (w: number, h: number) => {
    if (canvas.width !== w || canvas.height !== h) {
      canvas.width = w;
      canvas.height = h;
    }
    ctx.clearRect(0, 0, w, h);
  };
  // The preview's shadow falls from the whole layer — keyed picture plus the
  // stroke ink laid behind it — so the ink joins the silhouette here too;
  // a thick or offset stroke moves the shadow's edge with it.
  const ink = createRasterCanvas(2, 2);
  const inkCtx = ink.getContext("2d") as CanvasRenderingContext2D | null;
  // The ink paints from the selection (inset when the selection is the hole),
  // before any complement, so it rims what the stroke really shows.
  const paintInk = (w: number, h: number, tLocal: number): boolean => {
    const stroke = r!.stroke;
    if (!stroke || !inkCtx) return false;
    if (ink.width !== w || ink.height !== h) {
      ink.width = w;
      ink.height = h;
    }
    inkCtx.setTransform(1, 0, 0, 1, 0, 0);
    inkCtx.globalCompositeOperation = "source-over";
    inkCtx.clearRect(0, 0, w, h);
    paintStrokeInk(
      inkCtx,
      canvas as CanvasImageSource,
      w,
      h,
      stroke,
      tLocal,
      Math.min(w, h) / 1080,
      !!r!.invert
    );
    return true;
  };
  const matte = r!.matte ? assets.find((a) => a.id === r!.matte!.assetId) : undefined;
  if (!matte) return null;
  const reader = liveReader(matte);
  const mdur = Math.max(0.1, matte.duration || 0.1);
  return {
    at: async (tLocal) => {
      const srcT = still ? 0 : rt.srcAt(tLocal);
      const frame = await reader.frameAt(
        Math.min(Math.max(0, srcT - r!.matte!.in), mdur - 0.001)
      );
      if (frame.kind !== "ready") return null;
      stage(frame.width, frame.height);
      ctx.drawImage(frame.image, 0, 0);
      const px = ctx.getImageData(0, 0, frame.width, frame.height);
      matteLumaToAlpha(px.data);
      ctx.putImageData(px, 0, 0);
      const inked = paintInk(frame.width, frame.height, tLocal);
      // Inverted, the clip shows everything around the matte, so the shadow's
      // silhouette is the complement.
      if (r!.invert) {
        for (let i = 3; i < px.data.length; i += 4) px.data[i] = 255 - px.data[i];
        ctx.putImageData(px, 0, 0);
      }
      if (inked) {
        ctx.globalCompositeOperation = "destination-over";
        ctx.drawImage(ink, 0, 0);
        ctx.globalCompositeOperation = "source-over";
      }
      return canvas as CanvasImageSource;
    },
    dispose: () => reader.dispose(),
  };
}

/**
 * Paint the shadow a clip casts, frame-sized and transparent everywhere else.
 * The silhouette is the picture the clip really shows — its box, its rounded
 * corners, its mask, its pose, its keyed cutout — thrown behind itself and
 * then punched back out, so the graph can lay the result over the frame and
 * get what sitting behind the clip would have looked like. A moving clip
 * samples the shadow per frame, the way a keyframed mask samples its
 * coverage. Null without a shadow.
 */
async function renderClipShadowPictures(
  clip: VideoClip,
  asset: { width?: number; height?: number },
  W: number,
  H: number,
  dur: number,
  fps: number,
  tag: string,
  pngs: ExportPayload["pngs"],
  assets: MediaAsset[]
): Promise<SpecMask | undefined> {
  const sh = clip.boxStyle?.shadow;
  if (!sh) return undefined;
  // A cutout's shadow falls from the keyed subject, sampled per frame from
  // the matte, the way the preview casts it.
  const silhouette = removalShadowSilhouette(clip, assets);
  const scale = Math.min(W, H) / 1080;
  const frame = { width: W, height: H, scale };
  const rect = rectOf(clip);
  const box = { x: rect.x * W, y: rect.y * H, w: rect.w * W, h: rect.h * H };
  const radius = Math.max(0, (clip.boxStyle?.radius ?? 0) * scale);
  const mask = clip.mask && clip.mask.kind !== "subject" ? clip.mask : undefined;
  // The picture's own footprint inside the box — a fitted clip's shadow follows
  // the picture, not the empty margins beside it.
  const pic =
    asset.width && asset.height
      ? contentRect(box, asset.width, asset.height, clipCovers(clip), clipZoom(clip), clip.panX ?? 0, clip.panY ?? 0)
      : box;
  const shape = createRasterCanvas(W, H);
  const cover = createRasterCanvas(W, H);
  const canvas = createRasterCanvas(W, H);
  // The smear and the blur the preview lays on the shadow, made on first use.
  let smear: ReturnType<typeof createRasterCanvas> | null = null;
  let soft: ReturnType<typeof createRasterCanvas> | null = null;
  const anchor = { x: rect.x + rect.w / 2, y: rect.y + rect.h / 2 };
  const blobAt = async (tLocal: number) => {
    const sil = silhouette ? await silhouette.at(tLocal) : null;
    const shapeCtx = shape.getContext("2d") as CanvasRenderingContext2D;
    shapeCtx.setTransform(1, 0, 0, 1, 0, 0);
    shapeCtx.clearRect(0, 0, W, H);
    const pose = clipPosed(clip) ? clipFrameAt(clip, tLocal, W / H) : null;
    const look = pose ? elementLook(pose, scale) : null;
    if (pose) {
      shapeCtx.translate(pose.x * W, pose.y * H);
      shapeCtx.rotate((pose.rotation * Math.PI) / 180);
      shapeCtx.scale(pose.scale, pose.scale);
      shapeCtx.translate(-anchor.x * W, -anchor.y * H);
    }
    // The lit shape: the picture — a cutout's keyed silhouette in its place —
    // trimmed at the box's rounded corners.
    shapeCtx.save();
    shapeCtx.beginPath();
    shapeCtx.roundRect(box.x, box.y, box.w, box.h, radius);
    shapeCtx.clip();
    if (sil) {
      // The silhouette mirrors with the picture it was cut from.
      shapeCtx.save();
      if (clip.flipH || clip.flipV) {
        shapeCtx.translate(box.x + box.w / 2, box.y + box.h / 2);
        shapeCtx.scale(clip.flipH ? -1 : 1, clip.flipV ? -1 : 1);
        shapeCtx.translate(-(box.x + box.w / 2), -(box.y + box.h / 2));
      }
      shapeCtx.drawImage(sil, pic.x, pic.y, pic.w, pic.h);
      shapeCtx.restore();
    } else {
      shapeCtx.fillStyle = "#ffffff";
      shapeCtx.fillRect(pic.x, pic.y, pic.w, pic.h);
    }
    shapeCtx.restore();
    if (mask) {
      // The mask decides the rest of the shape; its luma becomes coverage.
      paintMaskLuma(cover, mask, tLocal, frame, anchor, 0, 0);
      shapeCtx.setTransform(1, 0, 0, 1, 0, 0);
      shapeCtx.globalCompositeOperation = "destination-in";
      shapeCtx.drawImage(cover as CanvasImageSource, 0, 0);
      shapeCtx.globalCompositeOperation = "source-over";
    }

    // A moving clip with motion blur casts from its streaked shape.
    let lit = shape;
    if (look && look.taps >= 2) {
      smear ??= createRasterCanvas(W, H);
      const smearCtx = smear.getContext("2d") as CanvasRenderingContext2D;
      smearCtx.setTransform(1, 0, 0, 1, 0, 0);
      smearCtx.clearRect(0, 0, W, H);
      drawStreak(smearCtx, shape as CanvasImageSource, 0, 0, look);
      lit = smear;
    }
    const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
    ctx.setTransform(1, 0, 0, 1, 0, 0);
    ctx.globalCompositeOperation = "source-over";
    ctx.clearRect(0, 0, W, H);
    ctx.save();
    ctx.shadowColor = shadowInk(sh);
    ctx.shadowBlur = Math.max(0, sh.blur) * scale;
    ctx.shadowOffsetX = (sh.x ?? 0) * scale;
    ctx.shadowOffsetY = (sh.y ?? 0) * scale;
    ctx.drawImage(lit as CanvasImageSource, 0, 0);
    ctx.restore();
    ctx.globalCompositeOperation = "destination-out";
    ctx.drawImage(lit as CanvasImageSource, 0, 0);
    ctx.globalCompositeOperation = "source-over";

    // The keyed blur softens the shadow as it softens the picture.
    if (!look || !(look.blur > 0) || !("filter" in ctx)) return rasterCanvasToPng(canvas);
    soft ??= createRasterCanvas(W, H);
    const softCtx = soft.getContext("2d") as CanvasRenderingContext2D;
    softCtx.setTransform(1, 0, 0, 1, 0, 0);
    softCtx.clearRect(0, 0, W, H);
    softCtx.filter = `blur(${look.blur.toFixed(2)}px)`;
    softCtx.drawImage(canvas as CanvasImageSource, 0, 0);
    softCtx.filter = "none";
    return rasterCanvasToPng(soft);
  };
  try {
    // A keyed subject moves every frame, so its shadow samples like an
    // animated mask does.
    const moves = (mask && isMaskAnimated(mask)) || clipKeyed(clip) || !!silhouette;
    if (!moves) {
      const name = `${tag}.png`;
      pngs.push({ name, blob: await blobAt(0) });
      return { file: name };
    }
    const rate = maskSampleFps(mask, dur, fps);
    const step = 1 / rate;
    const n = Math.max(1, Math.round(dur * rate));
    const frames: { file: string; duration: number }[] = [];
    for (let i = 0; i < n; i++) {
      const name = `${tag}_f${i}.png`;
      pngs.push({ name, blob: await blobAt(i * step) });
      frames.push({ file: name, duration: i === n - 1 ? Math.max(step, dur - (n - 1) * step) : step });
    }
    return { frames };
  } finally {
    silhouette?.dispose();
  }
}

/** Paint the clip's border ring — a stroked rounded rect along its box edge,
 * transparent everywhere else — sized to the segment the graph frames (the
 * full frame for track 0, the region box for overlays). The engine overlays
 * it onto the segment before fades, masks and pose, so the ring rides the
 * clip like the preview's stroke does. Null without a border. */
function renderClipBorderPng(
  clip: VideoClip,
  seg: { w: number; h: number },
  ring: { x: number; y: number; w: number; h: number },
  W: number,
  H: number
): Promise<Blob> | null {
  const bs = clip.boxStyle;
  if (!bs?.borderWidth) return null;
  const scale = Math.min(W, H) / 1080;
  const bw = bs.borderWidth * scale;
  const rad = Math.max(0, (bs.radius ?? 0) * scale);
  const canvas = createRasterCanvas(seg.w, seg.h);
  const ctx = canvas.getContext("2d") as CanvasRenderingContext2D;
  ctx.strokeStyle = bs.borderColor ?? "#ffffff";
  ctx.lineWidth = bw;
  ctx.beginPath();
  ctx.roundRect(ring.x + bw / 2, ring.y + bw / 2, ring.w - bw, ring.h - bw, Math.max(0, rad - bw / 2));
  ctx.stroke();
  return rasterCanvasToPng(canvas);
}

/** The spec names a file by its name in the project's media folder. */
const specFile = (a: MediaAsset) => a.fileName;

/** What a source's code values mean, for the spec: the profile the header
 * settled (with the person's override), and the matrix and range the file
 * decodes with. A still is sRGB, decoded to full-range RGB, and a block is
 * painted in Rec.709. The spec builder reads every video's header first
 * (`withAssetColors`), so a video without a record is a caller's bug. */
export function specColor(
  asset: Pick<MediaAsset, "type" | "color" | "colorProfile" | "block" | "fileName"> | undefined
): SpecClipColor {
  if (!asset || asset.type === "image") return { profile: "srgb", matrix: "bt709", fullRange: true };
  if (asset.block) return { profile: "rec709", matrix: "bt709", fullRange: false };
  const c = asset.color;
  if (!c) {
    throw new UserError("asset_color_unread", `The color of ${asset.fileName} was never read.`, { file: asset.fileName });
  }
  return { profile: asset.colorProfile ?? c.detected, matrix: c.matrix, fullRange: c.fullRange };
}

/** A camera card draws its own corners and shadow, so its clip's box style
 * stands aside in every painted picture (mask corners, border, shadow). */
const cardBoxless = (c: VideoClip): VideoClip => (c.card && c.boxStyle ? { ...c, boxStyle: undefined } : c);

/** The spec fields of a camera-card clip whose layer ships as `<tag>`
 * pieces: the pair stands in for the source, already framed to the box,
 * graded, looked and mirrored, so the engine frames it 1:1 and applies none
 * of those again. */
const cardEntry = (tag: string) => ({
  removal: { rgb: `${tag}_rgb.mp4`, alpha: `${tag}_a.mp4` },
  grade: undefined,
  look: undefined,
  effects: undefined,
  fit: "fill" as const,
  zoom: 1,
  panX: 0,
  panY: 0,
  flipH: undefined,
  flipV: undefined,
});

/** Build the export spec + overlay PNGs from the cut. Media already lives in
 * the project folder — the spec references it by file name; only overlay PNGs
 * travel with the request. Shared by full exports and the low-res hover proxy. */
export async function buildExportPayload(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  target: "export" | "preview" | "card" | "hls"
): Promise<ExportPayload> {
  // H.264 is an 8-bit delivery; an HDR picture takes HEVC Main 10 or ProRes.
  if ((doc.colorSpace ?? "sdr") !== "sdr" && settings.codec === "h264" && target === "export") {
    throw new UserError("export_h264_hdr", "H.264 is 8-bit. Export HDR as HEVC or ProRes.");
  }
  // Every video's color is read before the spec is: footage the lazy fill
  // has not reached would otherwise go out as Rec.709.
  doc = { ...doc, assets: await withAssetColors(doc.assets, doc) };
  // Elements shorter than an output frame widen onto the one they hold.
  doc = { ...doc, overlays: holdOverlays(doc.overlays, settings.fps) };
  const spans = getClipSpans(doc.clips, doc.assets);
  const duration = projectDuration(doc);
  const pngs: ExportPayload["pngs"] = [];
  const assetById = new Map(doc.assets.map((a) => [a.id, a]));
  // Cuts with an empty track 0 still export: track 0 becomes a bed of the
  // project's background color the length of the cut and the elements, layers
  // and soundtrack composite onto it — the same path as a gap before the first
  // track-0 clip. A cut of nothing but titles and shapes is that case for its
  // whole length. Anything on any row gives the project a duration, so having
  // one is the same question as having something to render.
  if (!(duration > 0)) {
    throw new UserError("export_timeline_empty", "Add something to the timeline first.");
  }

  // The person matte renders first, so the loops below attach subject fields
  // only when the effect will actually composite (no person segmenter, or no
  // person → everything renders plain, matching the preview's degrade). The
  // spec field keeps its `behindMask` name so older engines keep rendering
  // behind-tagged text.
  let behindMask: { file: string; from: number } | undefined;
  const wantsSubject =
    doc.overlays.some((o) => subjectMasked(o) && !o.hidden) ||
    doc.clips.some((c) => c.mask?.kind === "subject" && !c.hidden);
  if (wantsSubject) {
    const mask = await import("./maskVideo")
      .then((m) => m.renderSubjectMask(doc, duration))
      .catch(() => null);
    if (mask) {
      pngs.push({ name: "behind_mask.mp4", blob: mask.blob });
      behindMask = { file: "behind_mask.mp4", from: mask.from };
    }
  }
  /** A clip whose resting turn or fade rides as a one-key pose track: the
   * graph and the mask painter both read the picture's pose off `kf`, and a
   * single key holds flat, so the export renders the resting transform
   * through the path the animated one already takes. */
  const posed = (c: VideoClip): VideoClip => {
    if (!clipPosed(c) || clipKeyed(c)) return c;
    const rect = rectOf(c);
    return {
      ...c,
      kf: [
        {
          t: 0,
          x: rect.x + rect.w / 2,
          y: rect.y + rect.h / 2,
          scale: 1,
          rotation: c.rotation ?? 0,
          opacity: c.opacity ?? 1,
        },
      ],
    };
  };

  /** The subject entry a masked item ships, or undefined without a matte. */
  const subjectOf = (m: { invert?: boolean; feather?: number } | undefined) =>
    behindMask && m
      ? {
          ...(m.invert ? { invert: true } : {}),
          ...(m.feather ? { feather: m.feather } : {}),
        }
      : undefined;

  const clipEntries = spans.map((sp) => ({
    ...spanSoundSpec(sp, specFile),
    file: sp.asset.fileName,
    in: sp.clip.in,
    out: sp.clip.out,
    muted: sp.clip.muted,
    volume: sp.clip.volume ?? 1,
    sound: sp.clip.sound,
    fit: sp.clip.fit ?? "fit",
    zoom: clipZoom(sp.clip),
    panX: sp.clip.panX ?? 0,
    panY: sp.clip.panY ?? 0,
    flipH: sp.clip.flipH,
    flipV: sp.clip.flipV,
    frame: sp.clip.frame,
    speed: clipSpeed(sp.clip),
    speedCurve: sp.clip.speedCurve,
    reverse: sp.clip.reverse,
    smoothSlow: sp.clip.smoothSlow,
    transition: sp.transitionOut,
    // A cross dissolve carries its own window: the picture cuts, so the
    // server's blend must not see one. The handles are what the crossing
    // reaches into so both clips are audible over that cut.
    soundCross: sp.soundOut,
    soundAhead: sp.soundAhead,
    soundBack: sp.soundBack,
    // The style rides along with the overlap; the server resolves it to an
    // xfade name (and the cross-zoom ramps) itself, so the spec carries only
    // the id.
    transitionStyle: sp.clip.transitionStyle,
    transitionFeather: sp.clip.transitionFeather,
    transitionBand: sp.clip.transitionBand,
    animIn: sp.clip.animIn,
    animOut: sp.clip.animOut,
    look: sp.clip.look,
    lookAmount: sp.clip.lookAmount,
    effects: sp.clip.effects,
    effectsFrom: sp.clip.effectsFrom,
    hidden: sp.clip.hidden,
    // A still: the server loops the image for the clip's length instead of
    // trimming a source span.
    image: sp.asset.type === "image",
    grade: normalizeGrade(sp.clip.grade),
    color: specColor(sp.asset),
    mask: undefined as SpecMask | undefined,
    shadow: undefined as SpecMask | undefined,
    kf: posed(sp.clip).kf,
    motionBlur: sp.clip.motionBlur,
    border: undefined as string | undefined,
    removal: undefined as { rgb: string; alpha: string } | undefined,
    staged: undefined as boolean | undefined,
  }));
  // A block owns no file: its card is painted here at the output size and
  // travels with the job, so this render draws what the preview draws.
  for (let i = 0; i < spans.length; i++) {
    if (!spans[i].asset.block) continue;
    const name = `block_${i}.png`;
    pngs.push({
      name,
      blob: await rasterCanvasToPng(drawBlock(spans[i].asset, settings.width, settings.height)),
    });
    clipEntries[i].file = name;
    clipEntries[i].staged = true;
  }
  // Track-0 segments render at the full output frame (regioned clips pad out
  // to it), so their masks paint full-frame. A subject mask rides the shared
  // matte; painted pictures still travel beside it when the pose track keys
  // opacity, since opacity ships as coverage luma.
  for (let i = 0; i < spans.length; i++) {
    const c = posed(cardBoxless(spans[i].clip));
    const dur = Math.max(CLIP_MIN_SECONDS, retimeOf(c).len);
    const pictures = await renderClipMaskPictures(
      c,
      { x: 0, y: 0, w: settings.width, h: settings.height },
      settings.width,
      settings.height,
      dur,
      settings.fps,
      `mask_c${i}`,
      pngs
    );
    const subject = c.mask?.kind === "subject" ? subjectOf(c.mask) : undefined;
    if (pictures || subject) {
      clipEntries[i].mask = { ...(pictures ?? {}), ...(subject ? { subject } : {}) };
    }
    const rp = regionPx(c.frame, settings.width, settings.height);
    const ring = rp
      ? { x: rp.rx, y: rp.ry, w: rp.rw, h: rp.rh }
      : { x: 0, y: 0, w: settings.width, h: settings.height };
    const borderBlob = renderClipBorderPng(
      c,
      { w: settings.width, h: settings.height },
      ring,
      settings.width,
      settings.height
    );
    if (borderBlob) {
      const name = `border_c${i}.png`;
      pngs.push({ name, blob: await borderBlob });
      clipEntries[i].border = name;
    }
    clipEntries[i].shadow = await renderClipShadowPictures(
      c,
      spans[i].asset,
      settings.width,
      settings.height,
      dur,
      settings.fps,
      `shadow_c${i}`,
      pngs,
      doc.assets
    );
    // A removal clip's picture travels as its keyed layer, client-rendered:
    // a color/alpha pair the engine merges and frames in place of the source
    // decode. Grade and key are baked in (the entry's grade clears so the
    // engine never grades twice); the look stays on the entry — the engine
    // runs it over the flattened segment. A null is the declared degrade (no
    // matte yet — the export shows the plain picture, like the preview); a
    // broken render throws and fails the export instead of silently dropping
    // the cutout.
    if (c.card && !c.hidden) {
      const rp = regionPx(c.frame, settings.width, settings.height);
      const pieces = await renderCardPieces(spans[i].asset, spans[i].clip, doc.assets, {
        fps: settings.fps,
        frameW: settings.width,
        frameH: settings.height,
        box: rp ? { w: rp.rw, h: rp.rh } : { w: settings.width, h: settings.height },
      });
      if (pieces) {
        pngs.push({ name: `card_c${i}_rgb.mp4`, blob: pieces.rgb });
        pngs.push({ name: `card_c${i}_a.mp4`, blob: pieces.alpha });
        Object.assign(clipEntries[i], cardEntry(`card_c${i}`));
      }
    } else if (removalActive(c.removal) && !c.hidden) {
      const pieces = await renderRemovalPieces(spans[i].asset, spans[i].clip, doc.assets, {
        fps: settings.fps,
        maxShort: Math.min(
          2160,
          Math.round(Math.min(settings.width, settings.height) * clipZoom(c))
        ),
        // Effects bake into the keyed layer after the look, as the preview
        // wears them, so the look bakes in with them.
        bakeLook: !!c.effects?.length,
      });
      if (pieces) {
        pngs.push({ name: `removal_c${i}_rgb.mp4`, blob: pieces.rgb });
        pngs.push({ name: `removal_c${i}_a.mp4`, blob: pieces.alpha });
        clipEntries[i].removal = { rgb: `removal_c${i}_rgb.mp4`, alpha: `removal_c${i}_a.mp4` };
        clipEntries[i].grade = undefined;
        if (c.effects?.length) clipEntries[i].look = undefined;
        clipEntries[i].effects = undefined;
      }
    }
  }

  // The server's video graph is a sequential fold, so gaps between the
  // free-placed clips ship as explicit spacer segments: no file, hidden and
  // muted, which the server renders as black + silence for the gap's length.
  const spacer = (len: number) => ({
    file: "",
    in: 0,
    out: len,
    muted: true,
    volume: 0,
    fit: "fit" as const,
    zoom: 1,
    panX: 0,
    panY: 0,
    frame: undefined,
    speed: 1,
    transition: 0,
    hidden: true,
    image: false,
  });
  // An overlay-only cut has no track-0 spans: the whole base is one black bed.
  // Titles or sound that outlast the last shot run over black to the end.
  const last = spans[spans.length - 1];
  const tail = last ? duration - (last.start + last.len) : 0;
  const clips =
    spans.length === 0
      ? [spacer(duration)]
      : [
          ...spanSequence(spans).flatMap(({ gapBefore }, i) => [
            ...(gapBefore > 0 ? [spacer(gapBefore)] : []),
            clipEntries[i],
          ]),
          ...(tail > MICRO_GAP_S ? [spacer(tail)] : []),
        ];

  // Video tracks composited over track 0; hidden ones are dropped. Each
  // track's transitions and animations translate into per-clip head/tail
  // ramps: on an upper track a fade is an alpha fade (transparent, so the
  // tracks beneath show through), and a transition blends the incoming clip
  // in over the outgoing one — the incoming alpha-fades in for the overlap
  // while the outgoing stays opaque underneath it (cross zoom adds its zoom
  // ramps). Animations map fade/zoom natively; the styles that need frame
  // motion degrade to a fade up here.
  const overlayTracks = [...new Set(overlayLayers(doc.clips).map((c) => c.track))];
  // Entry → its source clip, so the mask loop below can paint per clip after
  // the entries assemble.
  const overlayClipOf = new Map<object, VideoClip>();
  const overlayVideos = overlayTracks.flatMap((track) => {
    const trackSpans = getClipSpans(doc.clips, doc.assets, track);
    const ramps = trackSpans.map(() => ({
      headFade: 0,
      tailFade: 0,
      headZoom: 0,
      tailZoom: 0,
      // Sound-only ramps: a dissolve on the sound leaves the picture alone,
      // so its windows ride apart from the alpha fades.
      headSound: 0,
      tailSound: 0,
      soundAhead: 0,
      soundBack: 0,
    }));
    trackSpans.forEach((sp, i) => {
      const r = ramps[i];
      const applyAnim = (a: ClipAnim | undefined, side: "head" | "tail") => {
        if (!a) return;
        const secs = Math.min(a.seconds, sp.len);
        if (overlayAnimStyle(a.style) === "zoom") {
          r[side === "head" ? "headZoom" : "tailZoom"] = secs;
        } else {
          r[side === "head" ? "headFade" : "tailFade"] = secs;
        }
      };
      // A transitioned joint owns its edges: that side's animation is held so
      // it never fights the transition's blend (mirrors preview and track 0).
      if (!((trackSpans[i - 1]?.transitionOut ?? 0) > 0)) applyAnim(sp.clip.animIn, "head");
      if (!(sp.transitionOut > 0)) applyAnim(sp.clip.animOut, "tail");
      if (sp.transitionOut > 0 && trackSpans[i + 1]) {
        const nr = ramps[i + 1];
        nr.headFade = Math.max(nr.headFade, sp.transitionOut);
        if ((sp.clip.transitionStyle ?? "crossfade") === "crosszoom") {
          r.tailZoom = Math.max(r.tailZoom, sp.transitionOut);
          nr.headZoom = Math.max(nr.headZoom, sp.transitionOut);
        }
      }
      if (sp.soundOut > 0 && trackSpans[i + 1]) {
        r.tailSound = Math.max(r.tailSound, sp.soundOut);
        ramps[i + 1].headSound = Math.max(ramps[i + 1].headSound, sp.soundOut);
      }
      r.soundAhead = sp.soundAhead;
      r.soundBack = sp.soundBack;
    });
    return trackSpans
      .map((sp, i) => ({ c: sp.clip, sp, ramp: ramps[i] }))
      .filter(({ c }) => !c.hidden && c.start < duration)
      .map(({ c, sp, ramp }) => {
        const entry = {
          ...spanSoundSpec(sp, specFile),
          file: assetById.get(c.assetId)!.fileName,
          in: c.in,
          out: c.out,
          start: c.start,
          track: c.track,
          frame: c.frame,
          // Pass `fit` through unset so the server's "default full-frame overlay
          // covers what's below" branch fires — normalizing to "fit" defeated it.
          fit: c.fit,
          zoom: clipZoom(c),
          panX: c.panX ?? 0,
          panY: c.panY ?? 0,
          flipH: c.flipH,
          flipV: c.flipV,
          muted: c.muted,
          volume: c.volume,
          sound: c.sound,
          speed: c.speed,
          speedCurve: c.speedCurve,
          reverse: c.reverse,
          smoothSlow: c.smoothSlow,
          image: assetById.get(c.assetId)!.type === "image",
          grade: normalizeGrade(c.grade),
          color: specColor(assetById.get(c.assetId)),
          look: c.look,
          lookAmount: c.lookAmount,
          effects: c.effects,
          effectsFrom: c.effectsFrom,
          mask: undefined as SpecMask | undefined,
          shadow: undefined as SpecMask | undefined,
          kf: posed(c).kf,
          motionBlur: c.motionBlur,
          border: undefined as string | undefined,
          removal: undefined as { rgb: string; alpha: string } | undefined,
          ...ramp,
        };
        overlayClipOf.set(entry, posed(cardBoxless(c)));
        return entry;
      });
  });
  // Upper-track segments render at their region box (letterboxed ones pad out
  // to it when masked), so their masks paint box-sized. Subject masks ride
  // the shared matte, with opacity-key luma pictures beside them.
  for (let i = 0; i < overlayVideos.length; i++) {
    const entry = overlayVideos[i];
    const c = overlayClipOf.get(entry);
    if (!c) continue;
    const region = regionPx(c.frame, settings.width, settings.height);
    const box = region
      ? { x: region.rx, y: region.ry, w: region.rw, h: region.rh }
      : { x: 0, y: 0, w: settings.width, h: settings.height };
    const olen = Math.max(CLIP_MIN_SECONDS, retimeOf(c).len);
    const pictures = await renderClipMaskPictures(
      c,
      box,
      settings.width,
      settings.height,
      olen,
      settings.fps,
      `mask_ov${i}`,
      pngs
    );
    const subject = c.mask?.kind === "subject" ? subjectOf(c.mask) : undefined;
    if (pictures || subject) {
      entry.mask = { ...(pictures ?? {}), ...(subject ? { subject } : {}) };
    }
    const borderBlob = renderClipBorderPng(
      c,
      { w: box.w, h: box.h },
      { x: 0, y: 0, w: box.w, h: box.h },
      settings.width,
      settings.height
    );
    if (borderBlob) {
      const name = `border_ov${i}.png`;
      pngs.push({ name, blob: await borderBlob });
      entry.border = name;
    }
    entry.shadow = await renderClipShadowPictures(
      c,
      assetById.get(c.assetId) ?? {},
      settings.width,
      settings.height,
      olen,
      settings.fps,
      `shadow_ov${i}`,
      pngs,
      doc.assets
    );
    // The keyed layer keeps its alpha over the tracks beneath, so the engine
    // applies no grade or look to it — both bake into the pieces here, the
    // way image overlays already carry their pixels ready-made.
    const oAsset = assetById.get(c.assetId);
    if (c.card && oAsset) {
      const pieces = await renderCardPieces(oAsset, c, doc.assets, {
        fps: settings.fps,
        frameW: settings.width,
        frameH: settings.height,
        box: { w: box.w, h: box.h },
      });
      if (pieces) {
        pngs.push({ name: `card_ov${i}_rgb.mp4`, blob: pieces.rgb });
        pngs.push({ name: `card_ov${i}_a.mp4`, blob: pieces.alpha });
        Object.assign(entry, cardEntry(`card_ov${i}`));
      }
    } else if (removalActive(c.removal) && oAsset) {
      const pieces = await renderRemovalPieces(oAsset, c, doc.assets, {
        fps: settings.fps,
        maxShort: Math.min(
          2160,
          Math.round(Math.min(settings.width, settings.height) * clipZoom(c))
        ),
        bakeLook: true,
      });
      if (pieces) {
        pngs.push({ name: `removal_ov${i}_rgb.mp4`, blob: pieces.rgb });
        pngs.push({ name: `removal_ov${i}_a.mp4`, blob: pieces.alpha });
        entry.removal = { rgb: `removal_ov${i}_rgb.mp4`, alpha: `removal_ov${i}_a.mp4` };
        entry.grade = undefined;
        entry.look = undefined;
        entry.effects = undefined;
      }
    }
  }

  // The library LUTs the grades name travel with the job, once per file, so
  // the engine parses the same bytes the tab drew through. One that cannot
  // be read fails the export here, naming it.
  const lutFiles = new Map<string, string>();
  for (const entry of [...clipEntries, ...overlayVideos]) {
    const id = lutIdOf(entry.grade);
    if (!id) continue;
    let file = lutFiles.get(id);
    if (!file) {
      const { fileName, bytes } = await loadLibraryLutFile(id);
      const ext = /\.([a-z0-9]+)$/i.exec(fileName)?.[1]?.toLowerCase() ?? "cube";
      file = `lut_${id.replace(/^lut:/, "").replace(/[^a-z0-9]/gi, "")}.${ext}`;
      pngs.push({ name: file, blob: new Blob([bytes as BlobPart]) });
      lutFiles.set(id, file);
    }
    entry.color = { ...entry.color, lutFile: file };
  }

  const audio = doc.audioClips
    .filter((a) => !a.hidden && a.start < duration && assetById.has(a.assetId))
    .map((a) => ({
      soundFrom: specSound(assetById.get(a.assetId)!, assetById, (x) => x.fileName),
      file: assetById.get(a.assetId)!.fileName,
      in: a.in,
      out: a.out,
      start: a.start,
      volume: a.volume,
      fadeIn: a.fadeIn ?? 0,
      fadeOut: a.fadeOut ?? 0,
      speed: a.speed,
      speedCurve: a.speedCurve,
      reverse: a.reverse,
      sound: a.sound,
      duck: a.duck,
      ...(a.lane ? { lane: a.lane } : {}),
    }));

  const overlays: {
    file?: string;
    start: number;
    end: number;
    x?: number;
    y?: number;
    blank?: string;
    frames?: { file: string; duration: number }[];
    /** The element trims by the shared person matte (invert = behind the
     * speaker). */
    subject?: { invert?: boolean; feather?: number };
    /** Its row: lane 0 is the top of the stack, and the effects interleave
     * with these by lane. */
    lane?: number;
  }[] = [];
  // Effect elements never rasterize: they ship as time-gated filter recipes
  // the server builds into the graph (the ids ride, never filter text). The
  // audio ones ride the same list and treat the mix rather than the picture.
  const effects = doc.overlays
    .filter((o) => o.kind === "effect" && !o.hidden && o.start < duration)
    .map((o) => ({
      effect: (o as { effect: string }).effect,
      amount: (o as { amount?: number }).amount,
      focus: (o as { focus?: { x: number; y: number } }).focus,
      ramp: (o as { ramp?: number }).ramp,
      leak: (o as { leak?: LeakCourse }).leak,
      glitch: (o as { glitch?: GlitchKind }).glitch,
      tone: (o as { tone?: FlashTone }).tone,
      rate: (o as { rate?: number }).rate,
      rhythm: (o as { rhythm?: FlashRhythm }).rhythm,
      fade: (o as { fade?: FlashFade }).fade,
      fadeEase: (o as { fadeEase?: EaseId }).fadeEase,
      lane: laneOf(o),
      start: o.start,
      end: Math.min(o.end, duration),
    }));

  // Every sticker the cut shows is read before any is drawn: one that cannot
  // be read stops the export by name.
  await requireStickers(doc.overlays.filter((o) => o.start < duration), doc.assets);

  for (let i = 0; i < doc.overlays.length; i++) {
    const o = doc.overlays[i];
    if (o.hidden || o.start >= duration) continue;
    if (o.kind === "effect") continue;
    // A blank title has no pixels to burn; shapes and stickers always render.
    if (isTextOverlay(o) && !o.text.trim()) continue;
    // A subject-masked element's stream must run its whole window so the
    // server can multiply the matte in per frame — the frames mechanism
    // covers that (a static element costs one frame plus the blank).
    const subject = subjectMasked(o) && o.mask ? subjectOf(o.mask) : undefined;
    const subjectFields = subject ? { subject } : {};
    // A Lottie sticker's pixels move on their own, so it exports as frames
    // even with no transform animation set.
    if (isOverlayAnimated(o) || (isStickerOverlay(o) && o.lottie) || subject) {
      // Animated: a region-cropped 30fps frame sequence that the server plays
      // as a concat-demuxer slideshow overlaid at the region. Presets sample
      // their heads and tails and reuse the middle; a keyframed pose changes
      // on its own schedule, so its whole span is sampled frame by frame.
      const set = await renderElementFrames(o, settings.width, settings.height, 30, doc.assets);
      const names = set.images.map((blob, j) => {
        const name = `overlay_${i}_f${j}.png`;
        pngs.push({ name, blob });
        return name;
      });
      const blank = `overlay_${i}_blank.png`;
      pngs.push({ name: blank, blob: set.blank });
      overlays.push({
        start: o.start,
        end: Math.min(o.end, duration),
        x: set.x,
        y: set.y,
        blank,
        frames: set.entries.map((e) => ({ file: names[e.image], duration: e.duration })),
        lane: laneOf(o),
        ...subjectFields,
      });
      continue;
    }
    const png = await renderStillPng(o, settings.width, settings.height, doc.assets);
    const key = `overlay_${i}.png`;
    pngs.push({ name: key, blob: png });
    overlays.push({
      file: key,
      start: o.start,
      end: Math.min(o.end, duration),
      lane: laneOf(o),
      ...subjectFields,
    });
  }

  // Subtitle stills travel in their own spec lane: the server plays each
  // subtitle track as one concat-demuxer slideshow (with a transparent filler
  // frame for gaps), so karaoke word windows don't each become an ffmpeg
  // input. Tracks overlap each other in time, so every track (language) gets
  // its own slideshow, marked by `lane`.
  const captions: { file: string; start: number; end: number; lane?: number }[] = [];
  if (doc.subtitles.showOnVideo) {
    const capStyle = captionStyle(doc.subtitles.style);
    for (let lane = 0; lane < subtitleLaneCount(doc.subtitles); lane++) {
      if (laneHidden(doc.subtitles, lane)) continue;
      const cues = laneCues(doc.subtitles, lane);
      const pos = trackPos(doc.subtitles, capStyle, lane);
      for (let i = 0; i < cues.length; i++) {
        const cue = cues[i];
        if (cue.start >= duration || !cue.text.trim()) continue;
        // A word effect burns one frame per span its picture holds still for;
        // otherwise the whole cue is a single still.
        const windows = doc.subtitles.wordHighlight
          ? cueWordFrames(cue, capStyle, doc.subtitles)
          : [{ start: cue.start, end: cue.end }];
        for (let wi = 0; wi < windows.length; wi++) {
          const win = windows[wi];
          if (win.start >= duration) break;
          const png = await renderElementPng(
            cueOverlay(
              cue,
              capStyle,
              i === 0,
              pos,
              doc.subtitles.wordHighlight ? (win.start + win.end) / 2 : undefined,
              // Wrap in design space (1080 short side) from the project ratio —
              // the same width the preview passes, whatever the render size.
              frameOf(doc.aspect).w
            ),
            settings.width,
            settings.height
          );
          const key = windows.length > 1 ? `sub_${lane}_${i}_${wi}.png` : `sub_${lane}_${i}.png`;
          pngs.push({ name: key, blob: png });
          captions.push({
            file: key,
            start: win.start,
            end: Math.min(win.end, duration),
            ...(lane > 0 ? { lane } : {}),
          });
        }
      }
    }
    if (captions.length > 0) {
      const blank = createRasterCanvas(settings.width, settings.height);
      pngs.push({ name: "sub_blank.png", blob: await rasterCanvasToPng(blank) });
    }
  }

  return {
    spec: {
      projectId,
      target,
      ...settings,
      ...(target === "export" ? { sourceSegments: sourceExportPlan(doc, settings) ?? undefined } : {}),
      ...(target === "export" && settings.stems ? { stemPlan: stemsFor(doc) } : {}),
      // The hover proxy, the share card and the streaming ladder are SDR web
      // pictures whatever the project delivers.
      colorSpace: target === "export" ? doc.colorSpace ?? "sdr" : "sdr",
      lutSize: CUT_COLOR.lutSize,
      lutSizeWide: CUT_COLOR.lutSizeWide,
      passes: CUT_EXPORT_PASSES,
      duration,
      background: projectBackground(doc.background),
      clips,
      audio,
      overlayVideos,
      overlays,
      captions,
      ...(effects.length ? { effects } : {}),
      ...(behindMask ? { behindMask } : {}),
    },
    pngs,
  };
}

/**
 * A cloud gate said no — the account is signed out, over its storage, or at
 * its render cap. The worker would say the same, so the export ends here with
 * the gate's own words.
 */
export class ExportRefusedError extends UserError {
  constructor(code: string, message: string, params: UserErrorParams = {}, readonly failure?: OperationFailure) {
    super(code, message, params);
  }
}

const startFailed = () => new UserError("export_start_failed", "Export failed to start.");
const saveFailed = () => new UserError("export_save_failed", "Could not save the export.");

/** Concurrent PUTs a cloud export's inputs go up on. */
const UPLOAD_LANES = 4;

function cloudRefusal(res: Response, body: { error?: string; bytes?: number; quotaBytes?: number } | null | undefined): ExportRefusedError | null {
  if (res.ok) return null;
  const failure = operationFailure(res.status, body);
  if (failure) {
    return new ExportRefusedError(failure.code, failure.message, {}, failure);
  }
  if (res.status !== 429 && res.status !== 413) {
    return null;
  }

  // The gate's own words keep their code; uncoded words read as they came.
  const reason = errorFromBody(body, startFailed());
  return reason instanceof UserError
    ? new ExportRefusedError(reason.code, reason.message, reason.params)
    : new ExportRefusedError("export_refused", reason.message, { reason: reason.message });
}

/** Serialize a payload to the engine's multipart form: PNGs in render order,
 * then the spec — the exact request shape from before the payload split. */
function exportFormFromPayload({ spec, pngs }: ExportPayload): FormData {
  const form = new FormData();
  for (const p of pngs) form.append(p.name, p.blob, p.name);
  form.append("spec", JSON.stringify(spec));
  return form;
}

/** Kick off an export on the given backend, returning the create response.
 * The backend is captured when the export starts, so a job keeps rendering
 * against its own backend even after the app rebinds to the other residency.
 * Local: the engine's multipart form. Cloud: presign the overlay PNGs, PUT
 * them straight to R2, then POST the JSON export body. */
async function postExport(
  projectId: string,
  payload: ExportPayload,
  outName: string,
  backend: CutBackend,
  extra?: Record<string, unknown>,
  signal?: AbortSignal
): Promise<Response> {
  signal?.throwIfAborted();
  if (backend.kind !== "cloud") {
    return backend.fetch("/api/cut/export", { method: "POST", body: exportFormFromPayload(payload) });
  }
  const overlays: { name: string; key: string }[] = [];
  if (payload.pngs.length > 0) {
    const pre = await backend.fetch("/api/cut/export/presign", {
      signal,
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        files: payload.pngs.map((p) => ({ name: p.name, bytes: p.blob.size })),
        target: (payload.spec as { target?: string }).target ?? "export",
      }),
    });
    const preBody =
      await apiJson<{ files?: { name: string; key: string; type?: string; url: string }[] }>(pre);
    if (!pre.ok || !preBody.files) {
      throw cloudRefusal(pre, preBody) ?? errorFromBody(preBody, startFailed());
    }
    const byName = new Map(preBody.files.map((f) => [f.name, f]));
    // The list carries a borrowed render's whole media set, so the PUTs go a
    // few at a time, and a cancel stops the ones still in flight.
    const queue = [...payload.pngs];
    await Promise.all(
      Array.from({ length: Math.min(UPLOAD_LANES, queue.length) }, async () => {
        for (let p = queue.shift(); p; p = queue.shift()) {
          const target = byName.get(p.name);
          if (!target) {
            throw startFailed();
          }
          // The content type the URL was signed with: it is the one the
          // signature covers, and for a video it differs from the blob's.
          await putSigned(target.url, p.blob, target.type || "image/png", { signal });
        }
      })
    );
    for (const p of payload.pngs) overlays.push({ name: p.name, key: byName.get(p.name)!.key });
  }
  signal?.throwIfAborted();
  return backend.fetch("/api/cut/export", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ spec: payload.spec, overlays, projectId, outName, ...extra }),
  });
}

/** The stems a cut exports as. A cut with nothing audible has none, and
 * asking for them is refused before anything renders. */
function stemsFor(doc: ExportDoc): StemDef[] {
  const stems = planStems(doc);
  if (stems.length === 0) {
    throw new ExportRefusedError("export_stems_silent", "Nothing in this cut makes a sound to split into stems.");
  }
  return stems;
}

/** The stems archive for an export that asks for one, rendered in this tab
 * from the same mix fold as the file's sound; null when it asks for none. */
async function stemsArchive(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  signal?: AbortSignal
): Promise<RenderedExport | null> {
  if (!settings.stems) return null;
  return renderStemsArchive(doc, settings, stemsFor(doc), {
    resolve: (asset) => renderAssetUrl(projectId, asset),
    signal,
  });
}

function renderAssetUrl(projectId: string, asset: MediaAsset): string {
  const state = useEditor.getState();
  return state.projectId === projectId
    ? state.assets.find((candidate) => candidate.id === asset.id)?.url ?? asset.url
    : asset.url;
}

/** The output's file name: what the user typed, or the project's name, under
 * the one sanitize rule every residency shares (the engine dedupes on disk). */
function exportOutName(settings: ExportSettings): string {
  return `${exportBaseName(settings.name ?? useEditor.getState().projectName)}${exportExtension(settings)}`;
}

/** Poll an export job to completion, reporting progress. Returns the file name. */
export async function pollExport(
  jobId: string,
  onProgress: (stage: string, ratio: number) => void,
  isCanceled: () => boolean = () => false,
  backend: CutBackend = getBackend()
): Promise<string> {
  for (;;) {
    if (isCanceled()) {
      throw new UserError("export_canceled", "Export canceled.");
    }
    await new Promise((r) => setTimeout(r, 400));
    const st = await backend.fetch(`/api/cut/export/${jobId}`);
    const status = await apiJson<{
      status?: string;
      progress?: number;
      outName?: string;
    }>(st);
    if (!st.ok || status.status === "error" || status.status === "canceled") {
      throw errorFromBody(status, new UserError("export_failed", "Export failed."));
    }
    onProgress("Rendering", status.progress ?? 0);
    if (status.status === "done") return status.outName ?? "export.mp4";
  }
}

/** Trigger a browser download of a finished export by job id. */
export function downloadExport(jobId: string, outName: string, backend: CutBackend = getBackend()) {
  downloadFile(backend.url(`/api/cut/export/${jobId}/file`), outName);
}

/** The engine on this Mac ships inside the app, so it can be older than the
 * page. An older build parses the spec by shape and drops the fields it does
 * not know — a range export would come back as the whole cut, a typed name
 * as the project's — so what the settings ask of the engine is checked
 * against what it says it carries, and the export refuses with the fix. */
/** Whether the cut plays a bound recording or a split edit anywhere: on a
 * clip of any track that sounds, or on the soundtrack. */
function cutUsesSoundFeatures(doc: ExportDoc): boolean {
  const byId = new Map(doc.assets.map((a) => [a.id, a]));
  const soundtrack = doc.audioClips.some((a) => {
    const asset = byId.get(a.assetId);
    return !!asset && !a.hidden && soundSourceOf(asset, byId).bound;
  });
  if (soundtrack) return true;
  const tracks = new Set(doc.clips.map((c) => c.track));
  return [...tracks].some((t) => getClipSpans(doc.clips, doc.assets, t).some(spanUsesSoundFeature));
}

async function assertEngineCarries(
  settings: ExportSettings,
  doc: ExportDoc,
  /** Who encodes the file: the engine in ffmpeg, or this tab, which only
   * hands the engine the finished files. */
  renderer: "engine" | "tab"
): Promise<void> {
  const engineRenders = renderer === "engine";
  const wants: [EngineFeature, boolean, string][] = [
    // An older engine would deliver the mix unmastered and drop the stems.
    ["export.loudness", engineRenders && settings.loudness !== undefined, "master the loudness"],
    ["export.stems", !!settings.stems, "export stems"],
    // An older engine plays the camera's own sound and no split edits, so a
    // cut that binds a separate recording or leads/trails its sound would
    // come back with the scratch track.
    ["export.sound", engineRenders && cutUsesSoundFeatures(doc), "play a separate sound recording or split edits"],
    // The color pipeline: an engine from before it grades nothing and folds
    // a log or HDR file the old way, so every export needs it.
    ["color.v2", true, "export this cut"],
    ["export.range", !!settings.range, "export a range"],
    ["export.name", !!settings.name, "name the file"],
    // An engine that does not know the codec falls through to H.264, which
    // would hand back a .mov of exactly the picture the master was chosen to
    // avoid.
    ["export.prores4444", settings.codec === "prores4444", "export a ProRes 4444 master"],
    // An engine from before HDR composites at 8 bits in BT.709 and tags the
    // file so; the HLG or PQ picture would land as a wrong SDR file.
    ["export.hdr", (doc.colorSpace ?? "sdr") !== "sdr", "export HDR"],
  ];
  const has = await engineFeatures();
  for (const [feature, wanted, what] of wants) {
    if (wanted && !has.has(feature)) {
      throw new ExportRefusedError("app_update_required", `Update the Donkey app to ${what}.`, {
        feature: feature.replace(".", "_"),
        what,
      });
    }
  }
}

/** Build the cut and hand it to the engine, returning the new job id. Progress,
 * cancel, download, and the finished-file actions are all driven from the
 * engine's job feed by the exports dock — this only kicks the render off, so it
 * returns the moment the job is queued and never blocks on the encode. */
export async function createExportJob(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings
): Promise<string> {
  const backend = projectOperation(projectId).backend;
  const outName = exportOutName(settings);
  if (backend.kind === "local") await assertEngineCarries(settings, doc, "engine");
  const payload = await buildExportPayload(projectId, doc, settings, "export");
  const res = await postExport(projectId, payload, outName, backend);
  const body = await apiJson<{ id?: string }>(res);
  if (!res.ok || !body.id) {
    throw cloudRefusal(res, body) ?? errorFromBody(body, startFailed());
  }
  return body.id;
}

/**
 * Render the cut in this tab and store the result, returning the finished job's
 * id.
 *
 * The worker path exists because a hosted page had no way to encode video; it
 * does now. Rendering here removes the round trip a queued export costs — the
 * media does not have to be pulled back out of storage into a container, and
 * nothing waits behind another account's render — and the file matches the
 * preview, because the same compositor drew both.
 *
 * Every residency: a cloud project's file goes up to storage, a browser
 * project's into the tab's own store, and a Mac project's to the engine on
 * this machine, which holds the job row and lands the file in the project's
 * folder.
 */
export async function runBrowserExport(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  opts: {
    onProgress?: (ratio: number) => void;
    signal?: AbortSignal;
    /** Dock-row label for a browser-resident render's tab-local job. */
    projectName?: string;
    /** The reserved job's id, as soon as it exists — the dock hides that row
     * while this tab is the thing rendering it. */
    onClaimed?: (jobId: string) => void;
  } = {}
): Promise<string> {
  const backend = projectOperation(projectId).backend;
  if (backend.kind === "browser") return runStoreExport(projectId, doc, settings, opts);
  if (backend.kind === "local") return runEngineExport(projectId, doc, settings, opts, backend);

  // The name and the destination are claimed before a frame is drawn, so a
  // render that is going to be refused for space or for the render cap is
  // refused now rather than after minutes of work. The claim is a job row, so
  // a second export started while this one renders sees it and takes the next
  // name instead of overwriting this one's file.
  const claim = await backend.fetch("/api/cut/export/client/presign", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    // The size this render is heading for — the number the dialog showed —
    // travels with the claim, so an account with no room for the file is told
    // now rather than after the encode.
    body: JSON.stringify({
      projectId,
      outName: exportOutName(settings),
      bytes: Math.round(
        estimateExportBytes(settings, deliverySpan(settings.range, projectDuration(doc)))
      ),
      // The stems ride the same claim: their name is held with the video's,
      // and the completion registers both.
      ...(settings.stems ? { stems: true } : {}),
    }),
  });
  const claimed = await apiJson<{ jobId?: string; url?: string; outName?: string; type?: string; stemsUrl?: string }>(claim);
  if (!claim.ok || !claimed.jobId || !claimed.url) {
    throw cloudRefusal(claim, claimed) ?? errorFromBody(claimed, startFailed());
  }
  if (settings.stems && !claimed.stemsUrl) {
    throw new UserError("cloud_stems_slot_missing", "The cloud did not hold a place for the stems.");
  }
  const jobId = claimed.jobId;
  opts.onClaimed?.(jobId);

  // The render keeps reading the project's store-served blob URLs after the
  // user opens another project; the hold keeps them alive until it finishes.
  holdRegistered(`/api/cut/projects/${projectId}/`);
  // The claim's row hears from the tab on a timer, so the worker's stale sweep
  // tells a render still drawing from a tab that closed mid-render.
  let reported = 0;
  const heartbeat = setInterval(
    () =>
      void backend
        .fetch(`/api/cut/export/client/${jobId}/progress`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ ratio: reported }),
        })
        .catch(() => {}),
    CLIENT_HEARTBEAT_MS
  );
  try {
    const rendered = await renderProjectToMp4(doc, settings, {
      // Read the asset's URL at the moment it is needed rather than off the
      // snapshot: a long render can outlive the links it started with, and the
      // store re-mints them behind it.
      resolve: (asset) =>
        renderAssetUrl(projectId, asset),
      signal: opts.signal,
      // The render is nearly all of the work; the upload is the tail of the bar.
      onProgress: ({ ratio }) => {
        reported = ratio * 0.9;
        opts.onProgress?.(reported);
      },
    });

    try {
      await putSigned(claimed.url, rendered.file, claimed.type ?? "video/mp4", {
        signal: opts.signal,
        onProgress: (fraction) => opts.onProgress?.(0.9 + fraction * 0.1),
      });
    } finally {
      // The file streamed from scratch disk into the upload; its space comes
      // back as soon as the upload is done with it.
      void rendered.discard();
    }
    const stems = await stemsArchive(projectId, doc, settings, opts.signal);
    if (stems) {
      try {
        await putSigned(claimed.stemsUrl!, stems.file, STEMS_MIME, { signal: opts.signal });
      } finally {
        void stems.discard();
      }
    }

    const done = await backend.fetch("/api/cut/export/client/complete", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jobId }),
    });
    const body = await apiJson<{ id?: string }>(done);
    if (!done.ok || !body.id) {
      throw cloudRefusal(done, body) ?? errorFromBody(body, saveFailed());
    }
    return body.id;
  } catch (err) {
    // A render that stopped — cancelled, failed, or refused — gives back the
    // name it was holding. Leaving the row behind would keep the name taken and
    // a render slot spent for a file that will never exist.
    void backend
      .fetch(`/api/cut/export/client/${jobId}/release`, { method: "POST" })
      .catch(() => {});
    throw err;
  } finally {
    clearInterval(heartbeat);
    releaseRegistered(`/api/cut/projects/${projectId}/`);
  }
}

/**
 * A Mac-resident project's export: the same in-tab render, with the finished
 * file streamed into the project's exports folder on this Mac. The engine
 * holds the job row — the file's name, the dock's slot, the progress every
 * other tab's dock shows — and encodes nothing: what the user watched on the
 * stage is what goes into the file, drawn by the same compositor and mixed
 * by the same graph.
 */
/** How often a tab render tells the engine it is still drawing. Well inside
 * the engine's silence window even for a hidden tab's throttled timers. */
const CLIENT_HEARTBEAT_MS = 5000;

async function runEngineExport(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  opts: NonNullable<Parameters<typeof runBrowserExport>[3]>,
  backend: CutBackend
): Promise<string> {
  await assertEngineCarries(settings, doc, "tab");
  const claim = await backend.fetch("/api/cut/export/client", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      projectId,
      container: settings.container,
      name: settings.name,
      ...(settings.stems ? { stems: true } : {}),
    }),
  });
  const claimed = await apiJson<{ id?: string; outName?: string }>(claim);
  if (!claim.ok || !claimed.id) {
    throw errorFromBody(claimed, startFailed());
  }
  const jobId = claimed.id;
  opts.onClaimed?.(jobId);
  // The engine's feed carries the progress to every other tab's dock; a
  // report every couple of percent is plenty for a bar.
  let reported = 0;
  const post = (ratio: number) =>
    void backend
      .fetch(`/api/cut/export/client/${jobId}/progress`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ ratio }),
      })
      .catch(() => {});
  const report = (ratio: number) => {
    if (ratio - reported < 0.02 && ratio < 1) return;
    reported = ratio;
    post(ratio);
  };
  // Each report is also the engine's sign that this tab is still drawing; a
  // long stretch with no new percent still says so on a timer, so a tab that
  // closed mid-render is told apart from one encoding a slow stretch.
  const heartbeat = setInterval(() => post(reported), CLIENT_HEARTBEAT_MS);
  try {
    const rendered = await renderProjectToMp4(doc, settings, {
      resolve: (asset) =>
        renderAssetUrl(projectId, asset),
      signal: opts.signal,
      // The render is nearly all of the work; the hand-in to the engine on
      // this machine is the tail of the bar.
      onProgress: ({ ratio }) => {
        opts.onProgress?.(ratio * 0.95);
        report(ratio * 0.95);
      },
    });
    // The stems land first: the video's hand-in settles the job.
    const stems = await stemsArchive(projectId, doc, settings, opts.signal);
    if (stems) {
      let landed: Response;
      try {
        landed = await backend.fetch(`/api/cut/export/client/${jobId}/stems`, {
          method: "PUT",
          headers: { "Content-Type": STEMS_MIME },
          body: stems.file,
          signal: opts.signal,
        });
      } finally {
        void stems.discard();
      }
      if (landed.status === 409) throw new DOMException("Export canceled.", "AbortError");
      if (!landed.ok) {
        throw errorFromBody(
          await apiJson<object>(landed),
          new UserError("export_stems_save_failed", "Could not save the stems."),
        );
      }
    }
    let done: Response;
    try {
      done = await backend.fetch(`/api/cut/export/client/${jobId}/file`, {
        method: "PUT",
        headers: { "Content-Type": deliveryContainer(settings.container).mime },
        body: rendered.file,
        signal: opts.signal,
      });
    } finally {
      // The file streamed from scratch disk into the engine's folder; its
      // space comes back as soon as the hand-in is done with it.
      void rendered.discard();
    }
    // The engine refuses a file for a job it no longer holds: the user
    // canceled this render from another dock. That is their stop, and it
    // ends here the way a cancel in this tab does.
    if (done.status === 409) throw new DOMException("Export canceled.", "AbortError");
    const body = await apiJson<{ id?: string }>(done);
    if (!done.ok || !body.id) {
      throw errorFromBody(body, saveFailed());
    }
    opts.onProgress?.(1);
    return body.id;
  } catch (err) {
    // A render that stopped — cancelled, failed — gives back the name it was
    // holding, so no row stays in the feed for a file that will never exist.
    // The release lands before the store hears of the stop, so the feed the
    // dock reads next is already clear of the row.
    await backend
      .fetch(`/api/cut/export/client/${jobId}/release`, { method: "POST" })
      .catch(() => {});
    throw err;
  } finally {
    clearInterval(heartbeat);
  }
}

/** A browser-resident project's stems, rendered in this tab and shelved
 * beside the video they go with. The two land together: stems that fail or
 * are canceled take the saved video with them. A failure is final, since the
 * cloud fallback mixes its stems in this same tab. */
async function saveStems(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  videoName: string,
  signal?: AbortSignal
): Promise<void> {
  if (!settings.stems) return;
  holdRegistered(`/api/cut/projects/${projectId}/`);
  try {
    const stems = (await stemsArchive(projectId, doc, settings, signal))!;
    try {
      const saved = await saveExport(projectId, stems.file, stemsArchiveName(videoName));
      const stored = await readFileAt(await exportsDir(projectId), saved);
      if (stored) registerBlobFile(`/api/cut/projects/${projectId}/exports/${encodeURIComponent(saved)}`, stored);
    } finally {
      void stems.discard();
    }
  } catch (err) {
    await dropStoredExport(projectId, videoName);
    if (err instanceof DOMException && err.name === "AbortError") throw err;
    if (err instanceof ExportRefusedError) throw err;
    const reason = err instanceof Error ? err.message : String(err);
    throw new ExportRefusedError("stems_save_failed", `The stems could not be saved: ${reason}`, { reason });
  } finally {
    releaseRegistered(`/api/cut/projects/${projectId}/`);
  }
}

/** A browser-resident project's export: the same in-tab render, with the
 * finished file written into the project's exports shelf in the browser store.
 * The job is a row in the tab-local feed, so the dock tracks, cancels, and
 * downloads it the way it does every other residency's. */
async function runStoreExport(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
  const requestedName = exportOutName(settings);
  const job = reserveBrowserExportJob(projectId, opts.projectName);
  opts.onClaimed?.(job.id);
  holdRegistered(`/api/cut/projects/${projectId}/`);
  try {
    const rendered = await renderProjectToMp4(doc, settings, {
      resolve: (asset) =>
        renderAssetUrl(projectId, asset),
      signal: opts.signal,
      onProgress: ({ ratio }) => {
        opts.onProgress?.(ratio);
        updateBrowserExportJob(job.id, { progress: ratio });
      },
    });
    let outName: string;
    try {
      outName = await saveExport(projectId, rendered.file, requestedName);
    } finally {
      void rendered.discard();
    }
    await saveStems(projectId, doc, settings, outName, opts.signal);
    // Serve the finished file from the store copy: the scratch file behind the
    // render is already gone, and these two paths are what the dock's download
    // button and the exports shelf resolve through backend.url().
    const saved = await readFileAt(await exportsDir(projectId), outName);
    if (saved) {
      registerBlobFile(`/api/cut/export/${job.id}/file`, saved);
      registerBlobFile(
        `/api/cut/projects/${projectId}/exports/${encodeURIComponent(outName)}`,
        saved
      );
    }
    updateBrowserExportJob(job.id, { status: "done", progress: 1, outName });
    return job.id;
  } catch (err) {
    removeBrowserExportJob(job.id);
    throw err;
  } finally {
    releaseRegistered(`/api/cut/projects/${projectId}/`);
  }
}

/**
 * Render a browser-resident project on the cloud worker.
 *
 * The tab is that project's whole machine, and when it cannot carry a render
 * — no encoder for the codec, ProRes, scratch storage that gives out — the
 * worker is the machine it borrows. The cut's media lives only in this
 * browser, so it rides up with the job beside the overlay stills, the worker
 * renders from those uploads, and the finished file comes back down into the
 * project's own exports folder. The cloud keeps nothing: the uploads and the
 * output are the job's scratch, gone when the job is dismissed or swept.
 */
async function renderBorrowedFile(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  target: "export" | "preview",
  opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<File> {
  const backend = captureCloudBackend();
  const requestedName = exportOutName(settings);
  let cloudJobId: string | null = null;
  const stop = () => opts.signal?.throwIfAborted();
  holdRegistered(`/api/cut/projects/${projectId}/`);
  try {
    const payload = await buildExportPayload(projectId, doc, settings, target);
    stop();
    for (const name of specMediaFiles(payload.spec as Parameters<typeof specMediaFiles>[0])) {
      const asset = doc.assets.find((a) => a.fileName === name);
      const url = asset ? renderAssetUrl(projectId, asset) : null;
      const blob = url ? resolveRegisteredBlob(url) : null;
      if (!blob) {
        throw new UserError("export_media_not_stored", `${name} is not in this browser's storage.`, { name });
      }
      payload.pngs.push({ name, blob });
    }
    const res = await postExport(projectId, payload, requestedName, backend, { mediaFrom: "overlays" }, opts.signal);
    const body = await apiJson<{ id?: string }>(res);
    if (!res.ok || !body.id) {
      throw cloudRefusal(res, body) ?? errorFromBody(body, new UserError("render_start_failed", "Render failed to start."));
    }
    cloudJobId = body.id;
    opts.onClaimed?.(cloudJobId);
    const outName = await pollExport(cloudJobId, (_stage, ratio) => opts.onProgress?.(ratio * 0.95), () => !!opts.signal?.aborted, backend);
    stop();
    const fileRes = await backend.fetch(`/api/cut/export/${cloudJobId}/file`, { signal: opts.signal });
    if (!fileRes.ok) {
      throw new UserError("render_fetch_failed", "Could not fetch the rendered file.");
    }
    const file = new File([await fileRes.blob()], outName, { type: deliveryContainer(settings.container).mime });
    stop();
    return file;
  } finally {
    if (cloudJobId) cancelExportJob(cloudJobId, backend);
    releaseRegistered(`/api/cut/projects/${projectId}/`);
  }
}

async function runBorrowedExport(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
  const job = reserveBrowserExportJob(projectId, opts.projectName);
  opts.onClaimed?.(job.id);
  try {
    // The worker borrows only the encode the tab cannot do; the stems are
    // sound, which this tab mixes itself, so they stay here.
    const file = await renderBorrowedFile(projectId, doc, { ...settings, stems: undefined }, "export", {
      ...opts,
      onProgress: (progress) => { opts.onProgress?.(progress); updateBrowserExportJob(job.id, { progress }); },
    });
    const saved = await saveExport(projectId, file, file.name);
    await saveStems(projectId, doc, settings, saved, opts.signal);
    const stored = await readFileAt(await exportsDir(projectId), saved);
    if (stored) {
      registerBlobFile(`/api/cut/export/${job.id}/file`, stored);
      registerBlobFile(`/api/cut/projects/${projectId}/exports/${encodeURIComponent(saved)}`, stored);
    }
    updateBrowserExportJob(job.id, { status: "done", progress: 1, outName: saved });
    return job.id;
  } catch (error) {
    removeBrowserExportJob(job.id);
    throw error;
  }
}

/** The cloud renders a browser-resident project's export when its tab
 * cannot; see `runBorrowedExport`. */
export function runBrowserExportInCloud(
  projectId: string,
  doc: ExportDoc,
  settings: ExportSettings,
  opts: Parameters<typeof runBrowserExport>[3] = {}
): Promise<string> {
  return runBorrowedExport(projectId, doc, settings, opts);
}

/** Cancel a running or queued export job, or retire a settled one from the
 * export-jobs feed. */
export function cancelExportJob(jobId: string, backend: CutBackend = getBackend()) {
  void backend.fetch(`/api/cut/export/${jobId}`, { method: "DELETE" }).catch(() => {});
}

/**
 * Build the share's streaming ladder for the cut as it stands.
 *
 * A share plays HLS rather than a single file, so this is what makes a shared
 * project watchable — see server/hlsLadder.ts for why. The render is queued and
 * not waited on: it re-encodes the whole cut once per rung, so the caller
 * returns immediately and the viewer's page polls for the ladder to appear.
 *
 * The top rung is capped at the source, so the frame size sent here is the
 * ceiling on what any viewer can ever see; it renders at the doc's own size.
 *
 * `shareSubtitles` is what the share grants, and it decides whether captions
 * are burned in at all. The doc is what the OWNER sees, so passing it through
 * unfiltered would put cue text in the pixels of a stream sent to viewers whose
 * share hides Subtitles — and pixels are past the point where the server's doc
 * filter can take it back out.
 */
export async function renderShareLadder(
  projectId: string,
  doc: ExportDoc,
  shareSubtitles: boolean,
  backend: CutBackend = getBackend()
): Promise<boolean> {
  // The master renders at "Original" — the ladder caps its top rung at this
  // frame, so anything given up here is given up for every viewer. The encode
  // preset is loosened because this master is an intermediate: every rung is
  // re-encoded from it, so its own compression never reaches a viewer.
  const settings: ExportSettings = {
    ...originalSettings(doc.aspect, doc.clips, doc.assets),
    preset: "veryfast",
  };
  // Both the flag and the cues go: the flag is what the burn-in reads, and
  // dropping the cues as well means no path through the pipeline can put this
  // text on screen for a viewer whose share does not grant it.
  const source: ExportDoc = shareSubtitles
    ? doc
    : { ...doc, subtitles: { ...doc.subtitles, cues: [], showOnVideo: false } };
  const burnedSubtitles = shareSubtitles && doc.subtitles?.showOnVideo === true;
  try {
    const payload = await buildExportPayload(projectId, source, settings, "hls");
    return (await postExport(projectId, payload, "master.m3u8", backend, { burnedSubtitles })).ok;
  } catch {
    // No clips yet, or a slot was busy. The share keeps playing whatever it
    // already had until a later attempt lands.
    return false;
  }
}

export function previewSettings(aspect: Aspect): ExportSettings {
  return { ...scaledFrame(aspect, 360), fps: 24, crf: 30, preset: "veryfast", ...DELIVERY_DEFAULTS };
}

export type PreviewArtifact = { id: string; projectId: string; revision: string; url: string; expiresAt?: number };
export type PreviewJob = PreviewArtifact & { status: "queued" | "done"; statusUrl?: string };

export async function submitPreviewSnapshot(
  snapshot: RenderSnapshot,
  onProgress: (stage: string, ratio: number) => void = () => {},
  signal?: AbortSignal
): Promise<PreviewJob> {
  const { operation: { projectId, backend }, doc, revision } = snapshot;
  signal?.throwIfAborted();
  const settings = previewSettings(doc.aspect);
  if (backend.kind === "browser") {
    const directory = await projectDir(projectId);
    if (!directory) {
      throw new UserError("project_not_in_browser", "Project not found in browser storage.");
    }
    holdRegistered(`/api/cut/projects/${projectId}/`);
    try {
      // The hover preview is an SDR web picture whatever the project delivers.
      const rendered = await canRenderInBrowser(doc, settings, "sdr")
        ? await renderProjectToMp4(doc, settings, {
            resolve: (asset) => asset.url, signal,
            onProgress: ({ ratio }) => onProgress("Rendering", ratio),
          })
        : {
            file: await renderBorrowedFile(projectId, doc, { ...settings, name: "preview" }, "preview", {
              signal, onProgress: (ratio) => onProgress("Rendering", ratio),
            }),
            discard: async () => {},
          };
      try {
        signal?.throwIfAborted();
        await writeFileAt(directory, "preview.mp4", rendered.file);
        const file = await readFileAt(directory, "preview.mp4");
        if (!file) {
          throw new UserError("preview_read_failed", "Could not read the rendered preview.");
        }
        const url = registerBlobFile(`/api/cut/projects/${projectId}/preview`, file);
        return { id: revision, projectId, revision, url, status: "done" };
      } finally {
        await rendered.discard();
      }
    } finally {
      releaseRegistered(`/api/cut/projects/${projectId}/`);
    }
  }
  const payload = await buildExportPayload(projectId, doc, settings, "preview");
  signal?.throwIfAborted();
  const res = await postExport(projectId, payload, "preview.mp4", backend, { revision }, signal);
  const body = await apiJson<{ id?: string }>(res);
  if (!res.ok || !body.id) {
    throw cloudRefusal(res, body) ?? errorFromBody(body, new UserError("preview_start_failed", "Preview failed to start."));
  }
  if (signal?.aborted) {
    cancelExportJob(body.id, backend);
    signal.throwIfAborted();
  }
  return {
    id: body.id, projectId, revision, status: "queued",
    url: backend.url(`/api/cut/export/${body.id}/file`),
    statusUrl: backend.url(`/api/cut/export/${body.id}`),
  };
}

export async function renderPreviewSnapshot(
  snapshot: RenderSnapshot,
  onProgress: (stage: string, ratio: number) => void = () => {},
  signal?: AbortSignal
): Promise<PreviewArtifact> {
  const job = await submitPreviewSnapshot(snapshot, onProgress, signal);
  if (job.status === "done") return job;
  const backend = snapshot.operation.backend;
  const cancel = () => cancelExportJob(job.id, backend);
  signal?.addEventListener("abort", cancel, { once: true });
  try {
    if (signal?.aborted) cancel();
    await pollExport(job.id, onProgress, () => signal?.aborted === true, backend);
    if (backend.kind === "cloud") {
      const response = await backend.fetch(`/api/cut/export/${job.id}`);
      const body = await apiJson<{ artifact?: { url: string; expiresIn: number } }>(response);
      if (!response.ok || !body.artifact) {
        throw errorFromBody(body, new UserError("preview_unavailable", "Preview is unavailable."));
      }
      return { id: job.id, projectId: job.projectId, revision: job.revision, url: body.artifact.url,
        expiresAt: Date.now() + body.artifact.expiresIn * 1000 };
    }
    return { id: job.id, projectId: job.projectId, revision: job.revision, url: job.url };
  } finally {
    signal?.removeEventListener("abort", cancel);
  }
}

/** Seconds of the cut a share card shows. */
const CARD_SECONDS = 5;

/** The cut's first `seconds`, as a doc. Clips keep their trim-in and lose
 * whatever hangs past the cut-off; everything starting after it drops. Used
 * for the share card, which is a five-second window onto the opening rather
 * than a render of the whole project. */
export function docFirstSeconds(doc: ExportDoc, seconds: number): ExportDoc {
  // The trim that ends a clip at `seconds` goes back through the clip's own
  // map, so a curved clip cuts at the source second really playing there.
  const clampOut = <
    T extends { start: number; in: number; out: number; speed?: number; speedCurve?: SpeedNode[]; reverse?: boolean },
  >(
    clip: T
  ): T => {
    const rt = retimeOf(clip);
    const room = seconds - clip.start;
    if (rt.len <= room) return clip;
    // The cut-off lands on the source second playing there: the tail of a
    // reversed clip is its `in`.
    return clip.reverse ? { ...clip, in: rt.srcAt(room) } : { ...clip, out: rt.srcAt(room) };
  };
  const starts = <T extends { start: number }>(item: T) => item.start < seconds;
  return {
    ...doc,
    clips: doc.clips.filter(starts).map(clampOut),
    audioClips: doc.audioClips.filter(starts).map(clampOut),
    overlays: doc.overlays
      .filter(starts)
      .map((o) => (o.end <= seconds ? o : { ...o, end: seconds })),
    subtitles: {
      ...doc.subtitles,
      cues: doc.subtitles.cues
        .filter(starts)
        .map((c) => (c.end <= seconds ? c : { ...c, end: seconds })),
    },
  };
}

/** Card frame size for an aspect: 16:9 sits close to the 1.91:1 social cards
 * want, and portrait cuts get a tall card rather than a letterboxed wide one. */
function cardSettings(aspect: Aspect): ExportSettings {
  return { ...scaledFrame(aspect, 720), fps: 15, crf: 26, preset: "veryfast", ...DELIVERY_DEFAULTS };
}

/** Render the project's link-preview card: the opening five seconds, which
 * the worker turns into the still frame and the animated thumbnail a shared
 * link unfurls with. Only shared projects have one, so this asks first and
 * costs a single small request when the project isn't shared.
 *
 * Best-effort throughout — a project with no footage, an unconfigured
 * backend, or a busy render slot simply keeps the card it already had. */
async function renderShareCard(projectId: string, doc: ExportDoc, backend: CutBackend, force = false): Promise<void> {
  if (backend.kind !== "cloud") return;
  const share = await shareSettings(projectId, backend);
  if (!share) return;
  const { cut, key } = sharedCut(doc, share.features?.timeline);
  if (!force && key !== null && lastShareRender.get(`${projectId}:card`) === key) return;
  let res: Response;
  try {
    const payload = await buildExportPayload(
      projectId,
      docFirstSeconds(cut, CARD_SECONDS),
      cardSettings(cut.aspect),
      "card"
    );
    res = await postExport(projectId, payload, "card.mp4", backend);
  } catch {
    return; // no clips yet
  }
  const body = (await res.json().catch(() => ({}))) as { id?: string };
  if (!res.ok || !body.id) return;
  await pollExport(body.id, () => {}, undefined, backend)
    .then(() => key !== null && lastShareRender.set(`${projectId}:card`, key))
    .catch(() => {});
}

type ShareRenderSettings = { features?: { subtitles?: boolean; timeline?: TimelineId } };

/** The project's share settings, or null when it is not shared. */
async function shareSettings(projectId: string, backend: CutBackend): Promise<ShareRenderSettings | null> {
  const res = await backend.fetch(`/api/cut/projects/${projectId}/share`).catch(() => null);
  if (!res?.ok) return null;
  const body = (await res.json().catch(() => null)) as { share?: ShareRenderSettings | null } | null;
  return body?.share ?? null;
}

/** The cut a share link plays: the timeline its settings name, Main by
 * default, whichever one the editor has open. A parked one carries a key of
 * what it draws, so editing the open timeline does not re-render a link that
 * plays another; the open one renders on every change, as it always has. */
function sharedCut(doc: ExportDoc, timeline: TimelineId | undefined): { cut: ExportDoc; key: string | null } {
  const { timeline: open = "main", timelines, ...cut } = doc;
  const want = timeline ?? "main";
  if (want === open) return { cut, key: null };
  const { aspect, ...body } = parkedTimeline({ aspect: cut.aspect, timeline: open, timelines: timelines ?? {} }, want);
  const parked = { ...cut, ...openedTimeline(body, doc.assets), aspect };
  return { cut: parked, key: shareRenderKey(parked) };
}

/** What each share render of a parked timeline last drew, this session. */
const lastShareRender = new Map<string, string>();
const shareRenderKey = (doc: ExportDoc) =>
  JSON.stringify([
    doc.clips, doc.audioClips, doc.overlays, doc.subtitles, doc.aspect, doc.background, doc.colorSpace,
    doc.assets.map((a) => [a.fileName, a.colorProfile, a.color, a.proxy?.fileName]),
  ]);

/** Rebuild the open project's share card from the cut as it stands. Fire and
 * forget: the card is an accessory to the link, and a failed render leaves the
 * previous one (or the generated placeholder) in place. */
export function refreshShareCard(projectId: string): void {
  const s = useEditor.getState();
  if (!s.loaded || s.projectId !== projectId) return;
  const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));
  void renderShareCard(projectId, snapshot.doc, snapshot.operation.backend, true).catch(() => {});
}

/**
 * Rebuild the open project's streaming ladder from the cut as it stands.
 *
 * Fire and forget, like the card: a failed render leaves the previous ladder
 * serving. Unlike the card, this is not cheap — it re-encodes the whole cut
 * once per rung — so it belongs on the same lull the hover proxy waits for
 * (the editor closing, or the tab going to the background), never on an
 * interaction like opening a dialog. The server drops it for a project that
 * has no share, so callers do not have to know.
 *
 * `shareSubtitles` decides whether captions are burned in; pass what the share
 * actually grants, not what the owner is looking at.
 */
export async function refreshShareLadder(projectId: string): Promise<void> {
  const s = useEditor.getState();
  if (!s.loaded || s.projectId !== projectId) return;
  const snapshot = captureRenderSnapshot(projectOperation(projectId), renderDoc(s));
  await refreshSnapshotLadder(snapshot, true);
}

async function refreshSnapshotLadder({ operation, doc }: RenderSnapshot, force = false): Promise<void> {
  const { projectId, backend } = operation;
  if (backend.kind !== "cloud") return;
  const share = await shareSettings(projectId, backend);
  if (!share) return;
  const { cut, key: drawn } = sharedCut(doc, share.features?.timeline);
  const subtitles = share.features?.subtitles === true;
  const key = drawn === null ? null : `${subtitles}:${drawn}`;
  if (!force && key !== null && lastShareRender.get(`${projectId}:ladder`) === key) return;
  // Like the open timeline's ladder, a job the worker accepted counts as drawn;
  // the next change to that cut renders it again.
  if ((await renderShareLadder(projectId, cut, subtitles, backend)) && key !== null)
    lastShareRender.set(`${projectId}:ladder`, key);
}

/** All derived representations consume the same captured document and transport. */
export async function refreshProjectPreviews(snapshot: RenderSnapshot, signal?: AbortSignal): Promise<void> {
  const { projectId, backend } = snapshot.operation;
  await renderPreviewSnapshot(snapshot, undefined, signal);
  await renderShareCard(projectId, snapshot.doc, backend);
  await refreshSnapshotLadder(snapshot);
}