Skip to content

Open source CapCut alternative.

TypeScript
50.4 KB
Raw Blame
"use client";

import { uploadCloudLibraryMedia, withCloudPreparedMedia } from "@/cut/lib/cloudLibraryUpload";
import type { LibraryUploadStage, LibraryUploadState } from "@/cut/lib/libraryUpload";
import { assetTypeOf } from "@/cut/lib/media";
import { CUT_COLOR } from "@/cut/lib/colorSettings";
import { lutFacts, parseLutFile } from "@donkeycut/effects-kit";
import { apiJson, getBackend } from "./backend";
import { cloudBackend } from "./backend/cloud";
import { readSnapshot, writeSnapshot } from "./cache";
import { contentKey } from "./contentKey";
import { pollCloudJob } from "./cloudJob";
import { downloadFromUrl } from "./download";
import { subtreeOf } from "./folderTree";
import { normalizeLink } from "./link";
import { installFontFace } from "./fontAssets";
import { fontLabelFor } from "./fontName";
import { itemName } from "./itemName";
import { SPECIMEN_FILE_SUFFIX, specimenPng } from "./fontSpecimen";
import {
  enrichAsset,
  importRemote,
  isFontFile,
  isLutFile,
  MAX_FONT_BYTES,
  presignedUpload,
  probeFileMeta,
  registerLandedAsset,
  uploadProjectMediaTo,
} from "./media";
import {
  activeResidency,
  availableResidencies,
  backendFor,
  libraryShelfKey,
  listedResidencies,
  type Residency,
} from "./residency";
import { probeMediaFile } from "./mediaRead";
import { storedMediaUrl } from "./mediaSync";
import { UserError, errorFromBody, replyError } from "./userError";
import { reportSwallowed } from "./report";
import { useEditor } from "./store";
import { playheadAt } from "./playhead";
import type {
  AssetType,
  LibraryTemplate,
  MediaAsset,
  TemplateMedia,
  TemplateSaveInput,
} from "./types";
import { landedSoundFrom } from "./projectTemplate";
import { IMAGE_CLIP_SECONDS, isLinkedAssetType, mediaUrl } from "./types";


/** A LUT goes by its file's name. The TITLE line inside the file is whatever
 * the tool that wrote it put there. */
export const lutFileName = (fileName: string) => fileName.replace(/\.[^.]+$/, "");

/** What a Library file is called wherever it is shown: a clip by the title
 * read off it, anything else by its name. */
export const libraryAssetName = (a: Pick<LibraryAsset, "name" | "title">) => a.title || a.name;

export interface LibrarySource {
  url: string;
  title?: string;
  uploader?: string;
  uploadDate?: string;
}

/** What a LUT's row says about its table. */
export type LutFactsMeta = { kind: "1d" | "3d" | "shaper+3d"; size: number };

export interface LibraryAsset {
  id: string;
  fileName: string;
  /** Uploaded source retained when playback needs conversion. */
  originalFile?: string;
  /** The playable copy of a master the browser cannot decode (a ProRes
   * file): what the shelf's cards and viewer play. `fileName` stays the
   * master, which a project copies. */
  proxyFile?: string;
  name: string;
  type: AssetType;
  duration: number;
  width?: number;
  height?: number;
  addedAt: number;
  folderId?: string | null;
  source?: LibrarySource;
  /** A linked item's identity — the content hash every project names it by.
   * Written by the page that checked the file, so a sync of a lazy kind
   * never reads the bytes back. */
  contentKey?: string;
  /** For a LUT, what kind of table the file holds. */
  lut?: LutFactsMeta;
  /** The source's own cover image, stored beside the media on the same shelf.
   * An import from a site that publishes one carries it; it is what a card and
   * the viewer show while the video itself loads. */
  posterFile?: string;
  /** How the asset entered the account from the iOS app: a phone camera
   * recording (shown in Camera Roll, kept out of the Library grid) or an
   * inspiration item. Cloud shelf only. */
  origin?: "camera" | "inspiration";
  /** A short name read off the clip itself — what is said in it and what is on
   * screen — standing in for `name` wherever the asset is shown. A phone
   * recording arrives named after the clock it was shot on, which tells nobody
   * which clip it is; this is what the card, the viewer and the assistant read
   * instead. Written once per clip by lib/clipTitle.ts. */
  title?: string;
  /** Which shelf this came off. Stamped on arrival — the servers each answer
   * for themselves and don't know the other exists. */
  residency: Residency;
}

export interface LibraryFolder {
  id: string;
  name: string;
  /** The folder this one is filed in; null is the top level. Folders nest
   * only within their own shelf. */
  parentId?: string | null;
  createdAt: number;
  residency: Residency;
}

/** A template as the library lists it: the stored doc plus the shelf it sits
 * on, so its media resolve against the right backend. */
export type LibraryTemplateItem = LibraryTemplate & { residency: Residency };

export interface LibraryData {
  assets: LibraryAsset[];
  folders: LibraryFolder[];
  templates: LibraryTemplateItem[];
}

/** Signed edge URLs for the cloud shelf's files, minted with its listing.
 *
 * The route that serves a library file answers with a redirect to the same
 * object, so it works — but a relative route path is not media-origin, and
 * that costs every read: two connections instead of eight, no chunk cache
 * (chunkCache.ts keys on the media origin), and a hop through the deployment
 * ahead of each range. A 55MB phone clip dragged onto the timeline reads its
 * container through that, which is the difference between a segment that
 * paints frames and one that sits black. The URL a card, a ghost and an
 * imported asset all read is this one, so a frame captured for any of them
 * serves the others.
 *
 * Tokens outlive their mint by at least an hour; a URL is retired well inside
 * that and the next listing mints it again. Anything unminted — a shelf listed
 * before the mint answered, a file uploaded since — falls back to the route,
 * which serves the same bytes. */
const MINT_TTL_MS = 30 * 60 * 1000;
const MINT_BATCH = 500;
/** A file's edge URL and the moment it was minted. Held per file rather than
 * per listing: a live shelf re-reads on a timer, and re-minting everything
 * each time would hand every card a new src and make the grid reload its
 * thumbnails on that timer. A URL already in hand stays the same string until
 * it nears expiry. */
const cloudMedia = new Map<string, { url: string; at: number }>();

/** The shelf route for a file: stable, self-healing, and the only form worth
 * persisting — a ref saved in a chat thread outlives any signed URL. */
export const libraryRouteUrl = (fileName: string, residency: Residency) =>
  backendFor(residency).url(
    `/api/cut/library/media/${encodeURIComponent(fileName)}`,
  );

/** How a live surface reads a library file: the minted edge URL while one is
 * in hand, the route otherwise. */
export const libraryMediaUrl = (fileName: string, residency: Residency) => {
  if (residency === "cloud") {
    const hit = cloudMedia.get(fileName);
    if (hit && Date.now() - hit.at < MINT_TTL_MS) return hit.url;
  }
  return libraryRouteUrl(fileName, residency);
};

/** The file a card or the viewer plays: the playable copy of a master the
 * browser cannot decode, else the file itself. A project copies the master. */
export const libraryPlaybackUrl = (a: Pick<LibraryAsset, "fileName" | "proxyFile" | "residency">) =>
  libraryMediaUrl(a.proxyFile ?? a.fileName, a.residency);

/** Mint edge URLs for everything a cloud listing names — media, covers, and
 * the files templates draw from. Best-effort: a shelf reads through the route
 * when this fails. */
async function mintCloudMediaUrls(shelf: LibraryData): Promise<void> {
  const files = [
    ...new Set(
      [
        ...shelf.assets.flatMap((a) => [a.fileName, a.posterFile, a.proxyFile]),
        ...shelf.templates.flatMap((t) => t.media.map((m) => m.fileName)),
      ].filter((f): f is string => !!f),
    ),
  ];
  // Only what has no URL in hand: on a shelf that has already been listed
  // that is a clip that just finished uploading, and usually nothing at all.
  const now = Date.now();
  const wanted = files.filter((f) => {
    const hit = cloudMedia.get(f);
    return !hit || now - hit.at >= MINT_TTL_MS;
  });
  if (!wanted.length) return;
  const batches: string[][] = [];
  for (let i = 0; i < wanted.length; i += MINT_BATCH) batches.push(wanted.slice(i, i + MINT_BATCH));
  // The batches go out together rather than one after the next, and each
  // keeps what it got: a batch that fails costs its own files the edge URL,
  // and the rest of the shelf still reads from the edge.
  await Promise.all(
    batches.map(async (batch) => {
      try {
        const res = await cloudBackend.fetch("/api/cut/library/presign-get", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ files: batch }),
        });
        if (!res.ok) return;
        const body = (await res.json()) as {
          urls?: { fileName: string; url: string }[];
        };
        for (const u of body.urls ?? []) cloudMedia.set(u.fileName, { url: u.url, at: Date.now() });
      } catch {
        // The route is the fallback for these files, same as an unminted one.
      }
    })
  );
}

/** The asset's cover image, when the import brought one back. */
export const libraryPosterUrl = (
  a: Pick<LibraryAsset, "posterFile" | "residency">,
) => (a.posterFile ? libraryMediaUrl(a.posterFile, a.residency) : undefined);

/** Save a library file to the user's Downloads folder, off the shelf it sits
 * on. The download goes through the route because it signs the attachment
 * name; a minted edge URL is signed for inline reads only. */
export function downloadLibraryAsset(
  a: Pick<LibraryAsset, "fileName" | "originalFile" | "residency">,
) {
  const file = a.originalFile ?? a.fileName;
  downloadFromUrl(libraryRouteUrl(file, a.residency), file);
}

async function fetchLibraryFrom(r: Residency): Promise<LibraryData> {
  const res = await backendFor(r).fetch("/api/cut/library");
  if (!res.ok) throw new UserError("library_load_failed", "Could not load the library.");
  const data = (await res.json()) as LibraryData;
  const shelf: LibraryData = {
    assets: (data.assets ?? []).map((a) => ({ ...a, residency: r })),
    folders: (data.folders ?? []).map((f) => ({ ...f, residency: r })),
    templates: (data.templates ?? []).map((t) => ({ ...t, residency: r })),
  };
  // Each half is stored on its own, so one can be recalled while the other is
  // re-read: that is what keeps the Mac's shelf listed with the app closed.
  writeSnapshot(libraryShelfKey(r), shelf);
  // Signed URLs expire, so they stay out of the snapshot and are minted with
  // the live listing instead.
  if (r === "cloud") await mintCloudMediaUrls(shelf).catch(() => {});
  return shelf;
}

/** One shelf as this browser last saw it, for a residency it can't ask right
 * now. Those files are still on that Mac; only the way to reach them is gone. */
async function rememberedLibraryFrom(
  r: Residency,
): Promise<LibraryData | null> {
  const hit = await readSnapshot<LibraryData>(libraryShelfKey(r));
  return hit?.value ?? null;
}

/** One residency's part of a listing already on screen, standing in for a
 * read of that shelf that failed. */
function heldShelf(r: Residency, held: LibraryData | undefined): LibraryData | null {
  if (!held) {
    return null;
  }
  return {
    assets: held.assets.filter((a) => a.residency === r),
    folders: held.folders.filter((f) => f.residency === r),
    templates: held.templates.filter((t) => t.residency === r),
  };
}

/**
 * The whole shelf: every residency's library in one listing, newest first. A
 * residency that fails keeps what `held` — the listing the caller already
 * shows — lists for it, so a read that blinks never empties the page; with
 * nothing held it is recalled when `remembered`, else left out. Only every
 * shelf failing is an error.
 *
 * `remembered` widens that from what this browser can reach to what the user
 * has: a shelf whose backend isn't answering is recalled from its last
 * listing. The Library tab asks for it, because those items exist and the user
 * is entitled to see them; the editor's library picker doesn't, because an
 * item it can't copy into the project has no business in a picker.
 */
export async function fetchLibrary(opts?: {
  remembered?: boolean;
  held?: LibraryData;
}): Promise<LibraryData> {
  const live = availableResidencies();
  const rs = opts?.remembered ? listedResidencies() : live;
  const parts = await Promise.all(
    rs.map((r) =>
      live.includes(r)
        ? fetchLibraryFrom(r).catch(() =>
            heldShelf(r, opts?.held) ??
            (opts?.remembered ? rememberedLibraryFrom(r) : null),
          )
        : rememberedLibraryFrom(r),
    ),
  );
  const got = parts.filter((p): p is LibraryData => p !== null);
  if (got.length === 0) throw new UserError("library_load_failed", "Could not load the library.");
  const byNewest = <T extends { addedAt: number }>(items: T[]) =>
    [...items].sort((a, b) => b.addedAt - a.addedAt);
  return {
    assets: byNewest(got.flatMap((p) => p.assets)),
    folders: got
      .flatMap((p) => p.folders)
      .sort((a, b) => a.createdAt - b.createdAt),
    templates: byNewest(got.flatMap((p) => p.templates)),
  };
}

/** Where an import is in its trip: waiting for a worker, pulling the media
 * down, or writing it onto the shelf. The library shows it on the tile the
 * import already took. */
export type ImportStage = "queued" | "downloading" | "saving";

/** The shape a link is likely to land in, before anything is known about it:
 * the short-form feeds are vertical, everything else is filmed wide. The tile
 * takes the real shape the moment the media lands. */
export function estimatedShape(url: string): { width: number; height: number } {
  return SHORT_FORM_URL.test(url)
    ? { width: 9, height: 16 }
    : { width: 16, height: 9 };
}

const SHORT_FORM_URL =
  /^https?:\/\/[^/]*(?:youtube\.com\/shorts\/|tiktok\.com\/|instagram\.com\/(?:reels?|stories)\/)/i;

/** Import a link into a shelf. `key` is the caller's own id for this import —
 * the pending card's — and rides to the cloud with the link, so a retry of
 * the same card gets the job it already queued and the link lands once. */
export async function importUrlToLibrary(
  url: string,
  residency: Residency = activeResidency(),
  onStage?: (stage: ImportStage) => void,
  key?: string,
): Promise<LibraryAsset[]> {
  url = normalizeLink(url);
  if (residency === "browser")
    return importUrlThroughCloud(url, "browser", onStage, key);
  onStage?.("downloading");
  const backend = backendFor(residency);
  const res = await backend.fetch("/api/cut/library/import-url", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url, ...(key ? { key } : {}) }),
  });
  // The engine downloads inside the request; the cloud answers {jobId} and a
  // worker does the fetch, so that side waits on the job.
  if (backend.kind === "cloud") {
    const started = await apiJson<{ jobId?: string }>(res);
    if (!res.ok || !started.jobId)
      throw replyError(res.status, started, new UserError("url_import_failed", "Could not import that URL."));
    const done = await pollCloudJob<{ assets?: LibraryAsset[] }>(
      started.jobId,
      backend,
      new UserError("url_import_failed", "Could not import that URL."),
      {
        onState: (state) =>
          onStage?.(state === "queued" ? "queued" : "downloading"),
      },
    );
    // The library holds media, so a source that turned out to be only words
    // fails here — the same line the engine's library import draws.
    if (!done.assets?.length)
      throw new UserError("link_no_media", "That link has no media to import.");
    return done.assets.map((a) => ({ ...a, residency }));
  }
  const body = await apiJson<LibraryAsset[]>(res);
  if (res.ok)
    return (Array.isArray(body) ? body : []).map((a) => ({ ...a, residency }));
  // The engine fetches with the tools it ships, and a site can refuse the
  // build it happens to carry — TikTok reads the requests it impersonates with
  // and answers with nothing usable. The cloud worker fetches with a different
  // one, so the link gets a second chance there and the bytes come back down
  // to this Mac. The engine's own reason stands if that side can't do it
  // either: it is the shelf the user was importing to.
  const reason = replyError(res.status, body, new UserError("url_import_failed", "Could not import that URL."));
  try {
    return await importUrlThroughCloud(url, residency, onStage, key);
  } catch {
    throw reason;
  }
}

const STAGED_GONE = 404;

/**
 * A link fetched by the cloud worker and landed on a shelf of this machine.
 *
 * Nothing in a page can pull a video off a YouTube or TikTok link, so the
 * browser shelf always imports this way; the engine falls back to it when the
 * fetch it runs itself comes back empty-handed. The worker stages the media in
 * the account's cloud shelf, where this browser can read it, and the bytes come
 * straight back down into the target shelf's own storage. The staged cloud copy
 * is dropped once they land, however this ends, so an import leaves nothing
 * behind on a shelf the user wasn't importing to.
 */
async function importUrlThroughCloud(
  url: string,
  target: Residency,
  onStage?: (stage: ImportStage) => void,
  key?: string,
): Promise<LibraryAsset[]> {
  onStage?.("downloading");
  const res = await cloudBackend.fetch("/api/cut/library/import-url", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url, ...(key ? { key } : {}) }),
  });
  const started = await apiJson<{ jobId?: string }>(res);
  if (!res.ok || !started.jobId)
    throw replyError(res.status, started, new UserError("url_import_failed", "Could not import that URL."));
  const done = await pollCloudJob<{ assets?: LibraryAsset[] }>(
    started.jobId,
    cloudBackend,
    new UserError("url_import_failed", "Could not import that URL."),
    {
      onState: (state) =>
        onStage?.(state === "queued" ? "queued" : "downloading"),
    },
  );
  // The library holds media, so a source that turned out to be only words
  // fails here — the same line the engine's library import draws.
  if (!done.assets?.length)
    throw new UserError("link_no_media", "That link has no media to import.");
  const landed: LibraryAsset[] = [];
  onStage?.("saving");
  try {
    for (const staged of done.assets) {
      const bytes = await cloudBackend.fetch(
        `/api/cut/library/media/${encodeURIComponent(staged.fileName)}`,
      );
      // A page resuming this key after its earlier run landed the media
      // finds the staged copy already dropped: the shelf holds it.
      if (bytes.status === STAGED_GONE && landed.length === 0) return [];
      if (!bytes.ok) throw new UserError("url_import_failed", "Could not import that URL.");
      const form = new FormData();
      form.append("file", await bytes.blob(), staged.fileName);
      form.append("name", staged.name);
      if (staged.posterFile) {
        const poster = await cloudBackend.fetch(
          `/api/cut/library/media/${encodeURIComponent(staged.posterFile)}`,
        );
        if (poster.ok)
          form.append("poster", await poster.blob(), staged.posterFile);
      }
      form.append(
        "meta",
        JSON.stringify({
          type: staged.type,
          duration: staged.duration,
          width: staged.width,
          height: staged.height,
        }),
      );
      if (staged.source) form.append("source", JSON.stringify(staged.source));
      const saved = await backendFor(target).fetch("/api/cut/library", {
        method: "POST",
        body: form,
      });
      const body = await apiJson<LibraryAsset>(saved);
      if (!saved.ok)
        throw replyError(saved.status, body, new UserError("url_import_failed", "Could not import that URL."));
      landed.push({ ...body, residency: target });
    }
  } catch (e) {
    // A part-written import is worse than none: the user reads an error and is
    // left holding half a link.
    for (const a of landed)
      await deleteFromLibrary(target, a.id).catch(() => {});
    throw e;
  } finally {
    for (const staged of done.assets) {
      await cloudBackend
        .fetch(`/api/cut/library/${staged.id}`, { method: "DELETE" })
        .catch(() => {});
    }
  }
  return landed;
}

/** Make a folder on a shelf, filed under `parentId` there (null for the
 * top level). */
export async function createLibraryFolder(
  name: string,
  residency: Residency = activeResidency(),
  parentId: string | null = null,
): Promise<LibraryFolder> {
  const res = await backendFor(residency).fetch("/api/cut/library/folders", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name, parentId }),
  });
  const body = await apiJson<LibraryFolder>(res);
  if (!res.ok) throw errorFromBody(body, new UserError("folder_create_failed", "Could not create folder."));
  return { ...body, residency };
}

/** Rename a folder, move it under another (null for the top level), or
 * both. A key left out keeps what the folder has. The shelf answers with the
 * folder as stored: a parent it could not honor reads back as the top level. */
export async function updateLibraryFolder(
  residency: Residency,
  id: string,
  patch: { name?: string; parentId?: string | null },
): Promise<LibraryFolder> {
  const res = await backendFor(residency).fetch(
    `/api/cut/library/folders/${id}`,
    {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(patch),
    },
  );
  if (!res.ok) throw new UserError("folder_update_failed", "Could not update folder.");
  return { ...((await res.json()) as Omit<LibraryFolder, "residency">), residency };
}

/** What a delete of `folders` takes off the shelf: those folders and the ones
 * filed under them, however deep, and the assets and templates filed in any
 * of them. A camera clip lives in Camera Roll whatever folder it is filed
 * under, so it stays; the shelf unfiles it. */
export function folderDeleteTakes(
  data: LibraryData,
  folders: readonly { id: string }[],
): { tree: Set<string>; assets: LibraryAsset[]; templates: LibraryTemplateItem[] } {
  const tree = new Set(folders.flatMap((f) => subtreeOf(data.folders, f.id)));
  const filed = (x: { folderId?: string | null }) => !!x.folderId && tree.has(x.folderId);
  return {
    tree,
    assets: data.assets.filter((a) => filed(a) && a.origin !== "camera"),
    templates: data.templates.filter(filed),
  };
}

/** Delete a folder and everything in it: folders, items and the notes filed
 * there. The cloud shelf takes its notes itself; on the others the notes go
 * once the folder has, so a delete that fails leaves them in place. */
export async function deleteLibraryFolder(
  residency: Residency,
  id: string,
): Promise<void> {
  let tree: string[] = [];
  if (residency !== "cloud") {
    const listing = await backendFor(residency).fetch("/api/cut/library");
    if (!listing.ok) throw new UserError("folder_read_failed", "Could not read the folder.");
    tree = subtreeOf((await listing.json() as LibraryData).folders, id);
  }
  const res = await backendFor(residency).fetch(
    `/api/cut/library/folders/${id}`,
    {
      method: "DELETE",
    },
  );
  if (!res.ok) throw new UserError("folder_delete_failed", "Could not delete folder.");
  if (residency !== "cloud") {
    const { deleteLibraryFolderNotes } = await import("@/cut/lib/notes");
    await deleteLibraryFolderNotes(residency, tree);
  }
}

/** File a library item — an asset or a template — into a folder on its own
 * shelf (`null` ungroups). Folders don't span residencies: a cloud item can't
 * move into a folder that lives on the Mac. */
export async function moveLibraryItem(
  residency: Residency,
  id: string,
  folderId: string | null,
): Promise<void> {
  const res = await backendFor(residency).fetch("/api/cut/library/move", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id, folderId }),
  });
  if (!res.ok) throw new UserError("library_item_move_failed", "Could not move item.");
}

/**
 * Carry a library file to another shelf, filed where it lands.
 *
 * A folder belongs to one shelf, so filing an item into one can mean crossing
 * shelves. Neither server can see the other, so the bytes come down here and go
 * back up, the item keeps its name and the link it was imported from, and the
 * copy left behind comes off.
 */
export async function carryAssetTo(
  asset: LibraryAsset,
  to: Residency,
  folderId: string | null,
): Promise<LibraryAsset> {
  const res = await backendFor(asset.residency).fetch(
    `/api/cut/library/media/${encodeURIComponent(asset.fileName)}`,
  );
  if (!res.ok) throw new UserError("library_shelf_read_failed", "Could not read that file off its shelf.");
  // A font's cover is baked from its bytes on the way in, so the shelf it
  // lands on draws its own — always the current sheet. A LUT has none.
  const from = isLinkedAssetType(asset.type) ? undefined : libraryPosterUrl(asset);
  const cover = from
    ? await backendFor(asset.residency)
        .fetch(
          `/api/cut/library/media/${encodeURIComponent(asset.posterFile!)}`,
        )
        .then((r) => (r.ok ? r.blob() : null))
        .catch(() => null)
    : null;
  const landed = await uploadToLibrary(
    new File([await res.blob()], asset.fileName),
    to,
    {
      // A clip carried to another shelf keeps the name the user reads, which
      // for a phone recording is the title read off the clip.
      name: asset.title || asset.name,
      ...(asset.source ? { source: asset.source } : {}),
      ...(cover ? { poster: cover } : {}),
    },
  );
  if (folderId) await moveLibraryItem(to, landed.id, folderId).catch(() => {});
  await deleteFromLibrary(asset.residency, asset.id).catch(() => {});
  return { ...landed, folderId };
}

/** A font is readable when the renderer can install it, so the check runs
 * through the installer seam: the file that passes here is exactly the file a
 * preview and a render job can draw with, and a renamed archive or a truncated
 * download is refused before a byte leaves the browser. It comes back with the
 * family name the font calls itself — the shelf's label and the font menu's —
 * and a specimen drawn in the face it just installed, which becomes the file's
 * cover, so a card never has to have the font installed to show it. */
async function checkFont(
  file: File,
): Promise<{ label: string; poster: Blob | null }> {
  if (file.size > MAX_FONT_BYTES) {
    const limit = Math.round(MAX_FONT_BYTES / 1024 ** 2);
    throw new UserError("font_too_large", `Fonts are limited to ${limit}MB.`, { limit });
  }
  const bytes = await file.arrayBuffer();
  const family = `lf-check-${file.size}`;
  try {
    await installFontFace(family, bytes);
  } catch {
    throw new UserError("font_unreadable", "That file isn't a font Cut can read.");
  }
  return {
    label: fontLabelFor(bytes, file.name),
    poster: await specimenPng(family).catch(() => null),
  };
}

/** A LUT is readable when the parser takes it, so the file is parsed once
 * here — a truncated download or a renamed text file is refused before a byte
 * leaves the browser. What comes back is the row's fields: the content key
 * every project names it by and what kind of table it is, so a sync lists
 * the shelf without reading the file again. */
async function checkLut(
  file: File,
): Promise<{ label: string; meta: LinkedUploadMeta }> {
  const maxBytes = CUT_COLOR.lutFileMaxBytes;
  if (file.size > maxBytes) {
    const limit = Math.round(maxBytes / 1024 ** 2);
    throw new UserError("lut_too_large", `LUT files are limited to ${limit}MB.`, { limit });
  }
  const bytes = await file.arrayBuffer();
  let parsed: ReturnType<typeof parseLutFile>;
  try {
    parsed = parseLutFile(file.name, new TextDecoder().decode(bytes));
  } catch (e) {
    // The parser's reason rides as a value; with none the sentence stands alone.
    const reason = e instanceof Error ? e.message.trim() : "";
    if (!reason) {
      throw new UserError("lut_unreadable", "That file isn't a LUT Cut can read.");
    }
    throw new UserError("lut_unreadable_reason", `That file isn't a LUT Cut can read. ${reason}`, { reason });
  }
  return {
    label: lutFileName(file.name),
    meta: {
      type: "lut",
      duration: 0,
      contentKey: await contentKey(bytes),
      lut: lutFacts(parsed),
    },
  };
}

/** The row a linked upload writes in place of a probe. */
type LinkedUploadMeta = {
  type: "font" | "lut";
  duration: 0;
  contentKey?: string;
  lut?: LutFactsMeta;
};

export async function uploadToLibrary(
  file: File,
  residency: Residency = activeResidency(),
  /** What the shelf should call it and where it came from, when the file is
   * arriving from somewhere that already knows — a carry from another shelf,
   * say. Left out, the file names itself and keeps whatever cover it makes. */
  keep: { name?: string; source?: LibrarySource; poster?: Blob; folderId?: string | null; state?: LibraryUploadState; onStage?: (stage: LibraryUploadStage) => void } = {},
): Promise<LibraryAsset> {
  const backend = backendFor(residency);
  // A linked item has no streams to measure. A font is checked by installing
  // it, and the check hands back the specimen the shelf keeps as its cover;
  // a LUT is checked by parsing it, and the check hands back its row.
  const font = isFontFile(file) ? await checkFont(file) : null;
  const lut = !font && isLutFile(file) ? await checkLut(file) : null;
  const linkedLabel = font?.label ?? lut?.label ?? null;
  const poster = keep.poster ?? font?.poster ?? null;
  const posterName = `${file.name}${SPECIMEN_FILE_SUFFIX}`;
  const linkedMeta: LinkedUploadMeta | null = font
    ? { type: "font", duration: 0 }
    : (lut?.meta ?? null);
  if (residency === "cloud") {
    const type = assetTypeOf(file);
    const meta = linkedMeta ?? (await probeFileMeta(file).catch(() => null));
    if ((!meta || !(meta.duration > 0)) && (type === "video" || type === "audio")) {
      return uploadCloudLibraryMedia(file, keep);
    }
    if (
      !meta ||
      (meta.type !== "image" && !isLinkedAssetType(meta.type) && !(meta.duration > 0))
    ) {
      throw new UserError("image_unreadable", "This image could not be read.");
    }
    const key = await presignedUpload(
      "/api/cut/library/presign",
      file,
      file.name,
      backend,
    );
    // The cover rides up as an object of its own; `complete` marks it and
    // records it against the asset.
    const posterKey = poster
      ? await presignedUpload(
          "/api/cut/library/presign",
          poster,
          posterName,
          backend,
        ).catch(() => null)
      : null;
    const res = await backend.fetch("/api/cut/library/complete", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        key,
        ...(posterKey ? { posterKey } : {}),
        meta: {
          name: keep.name ?? linkedLabel ?? file.name,
          ...(keep.source ? { source: keep.source } : {}),
          ...meta,
        },
      }),
    });
    const body = await apiJson<LibraryAsset>(res);
    if (!res.ok) throw replyError(res.status, body, new UserError("upload_failed", "Upload failed."));
    return { ...body, residency };
  }
  const form = new FormData();
  form.append("file", file, file.name);
  const name = keep.name ?? linkedLabel;
  if (name) form.append("name", name);
  if (keep.source) form.append("source", JSON.stringify(keep.source));
  if (poster) form.append("poster", poster, posterName);
  if (residency === "browser") {
    // Hosted preparation supplies missing decoders before the page stores media.
    const meta = linkedMeta ?? (await probeFileMeta(file).catch(() => null));
    if (
      !meta ||
      (meta.type !== "image" && !isLinkedAssetType(meta.type) && !(meta.duration > 0))
    ) {
      const type = assetTypeOf(file);
      if (type === "video" || type === "audio") {
        return withCloudPreparedMedia(file, async (prepared) => {
          await probeFileMeta(prepared);
          return uploadToLibrary(prepared, residency, { ...keep, name: keep.name ?? file.name });
        }, { ...keep, folderId: undefined });
      }
      throw new UserError("image_unreadable", "This image could not be read.");
    }
    form.append("meta", JSON.stringify(meta));
  } else if (linkedMeta) {
    form.append("meta", JSON.stringify(linkedMeta));
  } else {
    const type = assetTypeOf(file);
    if ((type === "video" || type === "audio") && !(await probeFileMeta(file).catch(() => null))) {
      keep.onStage?.("preparing");
      form.append("prepare", "true");
    }
  }
  const res = await backend.fetch("/api/cut/library", {
    method: "POST",
    body: form,
  });
  const body = await apiJson<LibraryAsset>(res);
  if (!res.ok && form.get("prepare") === "true") {
    return withCloudPreparedMedia(file, async (prepared) => {
      await probeFileMeta(prepared);
      return uploadToLibrary(prepared, residency, { ...keep, name: keep.name ?? file.name });
    }, { ...keep, folderId: undefined });
  }
  if (!res.ok) throw replyError(res.status, body, new UserError("upload_failed", "Upload failed."));
  return { ...body, residency };
}

export async function deleteFromLibrary(residency: Residency, id: string) {
  const res = await backendFor(residency).fetch(`/api/cut/library/${id}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new UserError("library_delete_failed", "Could not delete.");
}

/** Whether a library file on this shelf lands in the open project by a
 * server-side copy: the project's own backend holds both ends. */
const sameShelf = (residency: Residency) => residency === getBackend().kind;

/** Land one library file in the open project and return its stored name.
 *
 * On the project's own shelf the server does the copy without the bytes ever
 * reaching the browser. Off it — a cloud project reaching for a clip on this
 * Mac, or the reverse — neither server can see the other, so the bytes come
 * down here and go back up into the project. */
async function copyLibraryFileToProject(
  projectId: string,
  residency: Residency,
  fileName: string,
  assetId?: string,
  opts?: { onProgress?: (fraction: number) => void; signal?: AbortSignal },
): Promise<string> {
  const target = getBackend();
  if (assetId && sameShelf(residency)) {
    const res = await target.fetch("/api/cut/library/use", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ assetId, projectId }),
      signal: opts?.signal,
    });
    const body = await apiJson<{ fileName?: string }>(res);
    if (!res.ok || !body.fileName)
      throw replyError(res.status, body, new UserError("library_add_failed", "Could not add from library."));
    return body.fileName;
  }
  const bytes = await backendFor(residency).fetch(
    `/api/cut/library/media/${encodeURIComponent(fileName)}`,
    { signal: opts?.signal },
  );
  if (!bytes.ok) throw new UserError("library_file_read_failed", "Could not read that library file.");
  return uploadProjectMediaTo(
    target,
    projectId,
    await bytes.blob(),
    fileName,
    opts,
  );
}

/** Register a library asset in the open project's media, without placing it on
 * the timeline. Callers choose where it lands. Usable immediately: it plays
 * from the library's own route while the copy into the project runs behind
 * the editor (server-side on the asset's own shelf, download-and-upload
 * across residencies). */
export async function importLibraryAsset(
  projectId: string,
  lib: LibraryAsset,
): Promise<MediaAsset> {
  if (lib.type === "font")
    throw new UserError("font_not_for_timeline", "Fonts are used from the font menu, not the timeline.");
  if (isLinkedAssetType(lib.type))
    throw new UserError("lut_not_for_timeline", "A LUT is applied to a clip's color, from the Color panel.");
  // The project's media takes the name the shelf shows, so a phone
  // recording lands on the timeline under its title.
  const name = lib.title || lib.name;
  // A row uploaded unmeasured — a phone's camera-roll import carries no
  // length or size — is read here, before the clip is cut from it, so the
  // clip takes the footage's true length and the row learns it.
  let { duration, width, height } = lib;
  if (lib.type === "video" && !(duration > 0)) {
    const probe = await probeMediaFile(libraryMediaUrl(lib.fileName, lib.residency));
    duration = probe.duration;
    if (probe.width && probe.height) {
      width = probe.width;
      height = probe.height;
    }
    repairLibraryAssetMeta(lib, { duration, width, height }).catch((err: unknown) =>
      reportSwallowed("[cut] library meta repair failed", err, lib.fileName),
    );
  }
  // On this Mac the engine lands the file with a clone, and it is landed
  // before this returns: the asset registers at the project's own address
  // and plays from there. Registered on the shelf's address first, the
  // preview would open the file there, then open it again at the project's
  // once the copy reported — two readers and a walk restarted on a file
  // whose every keyframe is a 4K decode — while the strip and the waveform
  // went on reading the shelf's copy.
  if (lib.residency === "local" && sameShelf(lib.residency)) {
    const fileName = await copyLibraryFileToProject(
      projectId,
      lib.residency,
      lib.fileName,
      lib.id,
    );
    return registerLandedAsset(projectId, {
      fileName,
      name,
      type: lib.type,
      duration,
      width,
      height,
    });
  }
  return importRemote(
    projectId,
    {
      url: libraryMediaUrl(lib.fileName, lib.residency),
      name,
      fileName: lib.fileName,
      type: lib.type,
      duration,
      width,
      height,
      server: sameShelf(lib.residency),
    },
    (opts) =>
      copyLibraryFileToProject(
        projectId,
        lib.residency,
        lib.fileName,
        lib.id,
        opts,
      ),
  );
}

/** Write the length and size a probe read off a file back onto the shelf row
 * that was uploaded without them, so the card's time pill and the drop
 * preview show the footage's real length from the next listing on. The
 * browser shelf and the engine measure at ingest; only the cloud shelf takes
 * unmeasured rows, from the phone. */
async function repairLibraryAssetMeta(
  lib: LibraryAsset,
  meta: { duration: number; width?: number; height?: number },
): Promise<void> {
  if (lib.residency !== "cloud" || !(meta.duration > 0)) return;
  const res = await cloudBackend.fetch(`/api/cut/library/${encodeURIComponent(lib.id)}`, {
    method: "PUT",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(meta),
  });
  if (!res.ok) throw errorFromBody(await apiJson<unknown>(res), new UserError("library_asset_update_failed", "Could not update the library asset."));
}

/** Copy a library asset into the open project and add it to the timeline at
 * the playhead. */
export async function addLibraryAssetToProject(
  projectId: string,
  lib: LibraryAsset,
): Promise<MediaAsset> {
  const asset = await importLibraryAsset(projectId, lib);
  useEditor.getState().addAssetAtPlayhead(asset.id);
  return asset;
}

/** Save the current timeline selection as a by-reference template. It lands on
 * the project's own shelf: the server copies the media straight across. */
export async function saveTemplate(
  projectId: string,
  input: TemplateSaveInput,
): Promise<LibraryTemplateItem> {
  const residency = activeResidency();
  const res = await backendFor(residency).fetch("/api/cut/library/templates", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ projectId, ...input }),
  });
  const body = await apiJson<LibraryTemplate>(res);
  if (!res.ok) throw replyError(res.status, body, new UserError("template_save_failed", "Could not save the template."));
  return { ...body, residency };
}

/**
 * Carry a template to another shelf, filed where it lands.
 *
 * A template's media live privately in the library, so the carry takes them
 * with it: the files come down here and go up on the target shelf — presigned
 * objects in the cloud, a multipart post anywhere else — and the doc arrives in
 * the same order, since `layers` and `audio` point at `media` by index. The
 * template left behind comes off.
 */
export async function carryTemplateTo(
  t: LibraryTemplateItem,
  to: Residency,
  folderId: string | null,
): Promise<void> {
  const source = backendFor(t.residency);
  const files: File[] = [];
  for (const m of t.media) {
    const res = await source.fetch(
      `/api/cut/library/media/${encodeURIComponent(m.fileName)}`,
    );
    if (!res.ok)
      throw new UserError("template_media_read_failed", "Could not read that template's media off its shelf.");
    files.push(new File([await res.blob()], m.fileName));
  }
  const input = {
    name: t.name,
    folderId,
    duration: t.duration,
    media: t.media,
    layers: t.layers,
    audio: t.audio,
    texts: t.texts,
    cues: t.cues,
    ...(t.transitions ? { transitions: t.transitions } : {}),
    ...(t.stickers ? { stickers: t.stickers } : {}),
    ...(t.captions ? { captions: t.captions } : {}),
    ...(t.project ? { project: t.project } : {}),
    ...(t.sound ? { sound: t.sound } : {}),
    ...(t.grade ? { grade: t.grade } : {}),
  };
  const backend = backendFor(to);
  let res: Response;
  if (to === "cloud") {
    const keys: string[] = [];
    for (const f of files) {
      keys.push(
        await presignedUpload("/api/cut/library/presign", f, f.name, backend),
      );
    }
    res = await backend.fetch("/api/cut/library/templates/import", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ ...input, keys }),
    });
  } else {
    const form = new FormData();
    form.append("doc", JSON.stringify(input));
    for (const f of files) form.append("file", f, f.name);
    res = await backend.fetch("/api/cut/library/templates/import", {
      method: "POST",
      body: form,
    });
  }
  const body = await apiJson<LibraryTemplate>(res);
  if (!res.ok) throw replyError(res.status, body, new UserError("template_add_failed", "Could not add the template."));
  await deleteTemplate(t.residency, t.id);
}

/** Append a project asset to a library template as one more part at its end:
 * the server copies the file into the library and returns the updated
 * template. Same-shelf only — the copy happens server-side, where neither
 * backend can see the other's project media. */
export async function addAssetToLibraryTemplate(
  projectId: string,
  template: LibraryTemplateItem,
  asset: MediaAsset,
): Promise<LibraryTemplateItem> {
  if (template.residency !== getBackend().kind) {
    throw template.residency === "cloud"
      ? new UserError("template_in_cloud", "That template is in the cloud; this project isn't.")
      : new UserError("template_on_mac", "That template is on this Mac; this project isn't.");
  }
  const len = asset.type === "image" ? IMAGE_CLIP_SECONDS : asset.duration;
  const part =
    asset.type === "audio"
      ? { audio: { in: 0, out: len, volume: 1 } }
      : { layer: { in: 0, out: len, muted: false, track: 1, asClip: true } };
  const res = await getBackend().fetch(
    `/api/cut/library/templates/${template.id}/add`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        projectId,
        media: {
          fileName: asset.fileName,
          name: asset.name,
          type: asset.type,
          duration: asset.duration,
          width: asset.width,
          height: asset.height,
        },
        extend: len,
        ...part,
      }),
    },
  );
  const body = await apiJson<LibraryTemplate>(res);
  if (!res.ok) throw replyError(res.status, body, new UserError("template_append_failed", "Could not add to the template."));
  return { ...body, residency: template.residency };
}

export async function renameTemplate(
  residency: Residency,
  id: string,
  name: string,
): Promise<void> {
  const res = await backendFor(residency).fetch(
    `/api/cut/library/templates/${id}`,
    {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name }),
    },
  );
  if (!res.ok) throw new UserError("template_rename_failed", "Could not rename the template.");
}

/** Rename a Library file on its own shelf. Every kind takes the same call. */
export async function renameLibraryAsset(
  residency: Residency,
  id: string,
  name: string,
): Promise<void> {
  const res = await backendFor(residency).fetch(
    `/api/cut/library/${encodeURIComponent(id)}`,
    {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name: itemName(name) }),
    },
  );
  if (res.ok) return;
  const body = await apiJson<unknown>(res);
  // An engine from before renames answers the route with nothing.
  if (!body.error && residency === "local" && (res.status === 404 || res.status === 405))
    throw new UserError("app_update_to_rename", "Update the Donkey app to rename files on this Mac.");
  throw errorFromBody(body, new UserError("file_rename_failed", "Could not rename the file."));
}

export async function deleteTemplate(
  residency: Residency,
  id: string,
): Promise<void> {
  const res = await backendFor(residency).fetch(
    `/api/cut/library/templates/${id}`,
    {
      method: "DELETE",
    },
  );
  if (!res.ok) throw new UserError("template_delete_failed", "Could not delete the template.");
}

/** Land a template's media in the open project, in `template.media` order, and
 * return the stored file names. On the project's own shelf one call does the
 * whole copy server-side; off it each file rides through the browser. */
async function copyTemplateMediaToProject(
  projectId: string,
  template: LibraryTemplateItem,
): Promise<TemplateMedia[]> {
  if (template.residency === getBackend().kind) {
    const res = await getBackend().fetch(
      `/api/cut/library/templates/${template.id}/use`,
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ projectId }),
      },
    );
    const body = await apiJson<{ media?: TemplateMedia[] }>(res);
    if (!res.ok || !body.media)
      throw replyError(res.status, body, new UserError("template_add_failed", "Could not add the template."));
    return body.media;
  }
  const out: TemplateMedia[] = [];
  for (const m of template.media) {
    const fileName = await copyLibraryFileToProject(
      projectId,
      template.residency,
      m.fileName,
    );
    out.push({ ...m, fileName });
  }
  return out;
}

/** Copy a template's media into the open project and re-materialize its clips,
 * overlays, and captions at the playhead — everything editable, nothing baked. */
export async function addTemplateToProject(
  projectId: string,
  template: LibraryTemplateItem,
  at?: number,
): Promise<void> {
  const media = await copyTemplateMediaToProject(projectId, template);
  const urls = await Promise.all(media.map((m) => storedMediaUrl(projectId, m.fileName)));

  const s = useEditor.getState();
  // Each copied media file (in template.media order) becomes a project asset;
  // the layer/audio media indices resolve against this array. Enrichment gives
  // the new clips their filmstrip thumbnails and waveform peaks. A video's
  // separate recording binds to the copy of it.
  const assetIds = media.map(() => crypto.randomUUID().slice(0, 8));
  media.forEach((m, i) => {
    const soundFrom = landedSoundFrom(m, assetIds);
    const asset: MediaAsset = {
      id: assetIds[i],
      fileName: m.fileName,
      name: m.name,
      type: m.type,
      duration: m.duration,
      width: m.width,
      height: m.height,
      url: urls[i],
      ...(soundFrom ? { soundFrom } : {}),
    };
    s.addAsset(asset);
    void enrichAsset(asset);
  });
  s.insertTemplate(template, assetIds, at ?? playheadAt());
}

/** Copy a library template into the project as a project template: its media
 * land in the project's media folder and the template joins the Media panel.
 * Nothing is placed on the timeline. */
export async function importTemplateToProject(
  projectId: string,
  template: LibraryTemplateItem,
): Promise<void> {
  const media = await copyTemplateMediaToProject(projectId, template);
  useEditor.getState().addTemplate({
    name: template.name,
    duration: template.duration,
    media,
    layers: template.layers,
    audio: template.audio,
    texts: template.texts,
    cues: template.cues,
    ...(template.transitions ? { transitions: template.transitions } : {}),
    ...(template.stickers ? { stickers: template.stickers } : {}),
    ...(template.captions ? { captions: template.captions } : {}),
    ...(template.project ? { project: template.project } : {}),
  });
}

/** Materialize a project template onto the timeline at the playhead. Its media
 * already live in the project; assets are matched by file name and re-registered
 * if the Media entry was removed. */
export async function addProjectTemplateToTimeline(
  projectId: string,
  template: LibraryTemplate,
  at?: number,
) {
  const urls = await Promise.all(
    template.media.map((m) =>
      useEditor.getState().assets.some((a) => a.fileName === m.fileName)
        ? null
        : storedMediaUrl(projectId, m.fileName)
    )
  );
  const s = useEditor.getState();
  // A media file still in the project plays as it stands; a re-registered
  // one binds to its separate recording again.
  const existing = template.media.map((m) => s.assets.find((a) => a.fileName === m.fileName));
  const assetIds = existing.map((a) => a?.id ?? crypto.randomUUID().slice(0, 8));
  template.media.forEach((m, i) => {
    if (existing[i]) return;
    const soundFrom = landedSoundFrom(m, assetIds);
    const asset: MediaAsset = {
      id: assetIds[i],
      fileName: m.fileName,
      name: m.name,
      type: m.type,
      duration: m.duration,
      width: m.width,
      height: m.height,
      url: urls[i] ?? mediaUrl(projectId, m.fileName),
      ...(soundFrom ? { soundFrom } : {}),
    };
    s.addAsset(asset);
    void enrichAsset(asset);
  });
  useEditor.getState().insertTemplate(template, assetIds, at ?? playheadAt());
}

/** Copy a project asset into the shared library for reuse. It lands on the
 * project's own shelf, where the server can copy the bytes itself. */
export async function saveAssetToLibrary(
  projectId: string,
  asset: MediaAsset,
): Promise<LibraryAsset> {
  const residency = activeResidency();
  const res = await backendFor(residency).fetch("/api/cut/library/save", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      projectId,
      fileName: asset.fileName,
      name: asset.name,
    }),
  });
  const body = await apiJson<LibraryAsset>(res);
  if (!res.ok) throw replyError(res.status, body, new UserError("library_save_failed", "Could not save to library."));
  return { ...body, residency };
}